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ABSTRACT 


This  document  reports  the  results  of  four 
research  and  demonstration  efforts,  all  of  which 
bear  some  relationship  to  former  work  with  the 
PLANIT  computer-aided  instructional  system. 

The  first  part  of  the  report  discusses  the  success¬ 
ful  installation  of  PLANIT  on  a  PDP  11  mini-computer. 
Because  it  was  a  feasibility  study,  some  aspects  of 
the  installation  were  done  in  a  less  costly,  though 
less  efficient,  way  than  if  success  had  been  assured. 

Now  that  feasibility  has  been  established,  suggestions 
are  given  for  improving  the  installation. 


The  second  part  describes  the  utilization  of 
the  PLANIT  method  for  transportable  coding  on  a  new 
application,  an  on-line  query  and  retrieval  system. 
Several  aspects  of  this  demonstration  system  are 
discussed  and  a  User's  Manual  is  included  in  the 
Appendix. 

The  third  part  describes  a  program  which  was 
developed  for  converting  PLANIT  student  records  into 
a  format  which  the  Query  system  can  use.  This  provides 
a  ready  application  for  the  demonstration  of  the  Query 
system. 

The  fourth  and  final  part  describes  the  development 
of  a  test  program  which  interactively  checks  out  the 
MIOP  subroutine  which  must  be  written  locally  in  the 
process  of  installing  a  portable  computer  system,  either 
PLANIT  or  Query.  The  Test  Program  makes  the  check  out 
process  fast,  easy,  and  comprehensive.  Using  PLANIT  to 
perform  the  same  tests  is  difficult  beyond  the  ability 
of  most  local  personnel  who  are  still  new  to  the  system,' 

/A 

User  manuals  for  the  last  two  programs  are  also  j 
found  in  the  Appendix. 
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RESEARCH  IN  ADAPTABLE  PROGRAMMING 
TO  ACHIEVE  COMPUTER  INDEPENDENCE 

FINAL  REPORT 


INTRODUCTION 


The  research  described  in  this  report  is  in  many 
ways  nn  outgrowth  of  earlier  work  with  PLANIT. 

PL AN IT  (Programming  LANguage  for  Interactive 
Teaching)  is  a  publicly  owned  computer  software 
system  used  for  authoring  and  administering  computer- 
assisted  instruction  scenarios  interactively  through 
time-sharing  to  a  group  of  trainees.  Support  for  its 
development  came  from  the  National  Science  Foundation 
and  from  the  United  States  Army  Research  Institute 
(ARI). 

The  one  feature  that  makes  PLANIT  unique  in  its 
class  is  its  transportable  design.  Much  of  the  earlier 
developmental  effort  was  to  achieve  such  a  transportable 
package  as  PLANIT  now  is.  It  may  be  an  over-simplification 
to  say  that  NSF's  interest  in  PLANIT  was  to  see  such  a 
software  design  worked  out,  after  which  ARI  has  validated 
the  design  and  put  it  to  work. 

Having  successfully  demonstrated  that  a  portable 
software  package  like  PLANIT  can  be  used  on  a  variety  of 
hardware  in  a  variety  of  operating  environments  to 
dispense  training  scenarios,  ARI  chose  to  expand 
their  investigation  to  include  software  designs  which 
are  fully  portable  like  PLANIT,  but  to  be  used  in  totally 
different  applications. 

Therefore,  this  report  Includes  both  aspects  of 
their  interest.  One  is  the  further  probing  of  the 
extent  of  PLANIT's  portability,  namely  involving  a 
mini-computer  this  time.  The  other  is  the  extension  of 
that  design  to  a  new  application,  namely  an  interactive 
information  retrieval  subsystem  of  a  data  management 
system. 


A  third  component  of  the  effort  links  the  first 
two  while  at  the  same  time  providing  another  new 
environment  for  portable  programming,  a  batch  program 
which  moves  data  from  PLAN1T  into  data  base  format  for 
the  information  retrieval  system. 

Finally,  a  much  needed  component,  providing  yet 
another  operating  environment  in  which  to  tost  trans¬ 
portable  coding  design,  an  interface  test  program  was 
developed  which  checks  out  a  target  installation 
interface,  either  verifying  the  correct  performance 
of  all  of  its  functions  or  providing  corrective  diag¬ 
nostic  feedback  for  those  functions  which  may  be  exec¬ 
uting  improperly. 

The  con.  act  also  provided  some  technical  assistance 
and  some  routine  kinds  of  maintenance  changes  to 
Pl.ANIT  which  have  been  documented  in  monthly  reports. 
However,  the  research  results  which  are  of  interest 
in  this  report  center  on  the  above  four  major  efforts. 


PURPOSE 


The  purpose  of  this  effort  was  to  extend  the 
range  of  PLANIT's  appl icability  to  a  new  clnss  of 
computers  (i.e.  mini -computers') ,  and  to  extend  the 
transportability  design  from  PLAN IT  to  different  kinds 
of  computer  software  applications. 

Enlarging  on  the  first  part,  PLANIT  was  first 
demonstrated  on  several  conventional  commercial  digital 
computers.  Although  these  differed  in  all  the  ways  that 
could  be  expected  (e.g.  word  sizos,  character  sets, 
input/out  put  conventions,  etc.),  yet  all  shared  oper¬ 
ating  environments  which  had  many  similarities,  including 
FORTRAN  compilers,  utility  software  for  real  time 
applications,  etc.  The  ARI  effort  that  put  PI.ANIT  on 
TACFIRE  was  a  test  of  another  magnitude  to  see  if  PLANIT 
would  operate  in  a  completely  fori^gn  environment. 

PI.ANIT  now  runs  on  TACFIRE,  performing  as  well  or  better 
than  most  of  us  had  hoped.  Not  only  does  it  execute 
in  an  identical  manner  to  the  commercial  counterparts, 
but  tvaining  scenarios  prepared  on  either  run  without 
change  on  the  other. 

In  further  probing  the  limits  of  PLANIT’s  appli¬ 
cability,  ARI  undertook  the  sponsorship  of  the  instal- 


lation  of  PLANIT  on  yot  a  different  class  of  computers, 
the  mini-computer.  In  its  various  publications,  the 
PLANIT  literature  has  often  stated  that  its  size  and 
design  make  it  unsuitable  for  mini-computers.  In  the 
face  of  that,  ARI  determined  to  test  its  feasibility. 
The  results  wore  completely  successful,  the  details 
of  which  contribute  to  a  large  section  of  this  report. 

Enlarging  on  the  second  part  of  the  purpose  (i.e. 
to  extend  the  limits  of  the  design's  applicability), 
the  results  are  very  encouraging  and  clearly  show  the 
direction  that  further  research  ought  to  take. 

In  particular,  this  investigation  sought  to 
dissect  from  PLANIT  a  discreet  subsystem  that  might 
be  identified  as  its  operating  system.  Called  MAGIC 
(Machine  Adaptable  Generated  Interactive  Console), 
that  operating  system  was  then  to  be  used  to  drive  a 
different  computer  application.  During  the  course  of 
the  effort,  that  application  became  defined  to  be  an 
information  retrieval  subsystem  for  a  data  management 
system,  to  be  patterned  after  the  TRW  GIM  II  informa¬ 
tion  retrieval  language.  Being  primarily  a  research 
effort,  the  goal  did  not  encompass  a  complete  system, 
ready  for  export  to  a  user  community.  Rather,  this 
version  was  to  be  suitable  for  demonstration  purposes. 

The  reader  is  encouraged  to  continually  be 
reminded  of  these  research-oriented  purposes  as  a 
frame  of  reference  for  the  discussion  that  will  follow 
on  each  of  the  component  pieces  of  the  project. 


INSTALLATION  OF  PLAN  IT  ON  A  POP  tl 


In  the  early  years  of  PLANIT's  design,  beginning 
in  1968,  a  class  of  computers  were  commercially  avail¬ 
able  that  were  being  called  mini-computers.  The 
Digital  Equipment  Corporation's  POP  8  computer  was  one 
of  several  that  shared  certain  similarities,  making 
them  a  part  of  the  mini-computer  class.  Although 
the  first  PDP  8's  were  about  as  large  ns  a  desk, 
newer  versions  were  soon  marketed  that  would  easily 
sit  on  a  desk,  being  little  larger  than  a  broadbox. 

These  computers  generally  had  architecture  of  12-bit 
words  (some  more,  some  less),  and  a  simplified  set 
of  basic  Instructions. 

Having  had  some  prior  experience  with  a  proto¬ 
type  for  PLANIT,  it  was  completely  clear  that  computers 
of  this  sort  would  not  have  the  size  or  sophistication 
necessary  to  run  a  portable  PLANIT.  Therefore,  it  was 
necessary  to  determine  a  reasonable  lowex’  limit  of 
hardware  architecture  in  order  to  provide  the  necessary 
guidelines  to  the  programmers  of  the  system.  Such 
things  as  higher  level  language  capabilities  and  the 
magnitude  and  precision  of  numbers  that  could  be  used 
demanded  such  guidelines. 

In  order  to  choose  these  parameters,  some  estimates 
were  calculated  of  what  the  finished  PLANIT  system  might 
look  like.  Some  of  the  important  calculations 
from  that  effort  were  core  sizes  to  run  the  system  and 
data  characteristics  which  would  determine  the  dimensions 
of  memory  needed.  Thus,  PLANIT  was  projected  to  need 
the  equivalent  of  256,000  characters  of  core  memory  to 
run  well,  and  a  minimum  of  128,000  characters  of  core  to 
run  a  completely  scaled-down  version.  Upper  limits  of 
core  at  that  time  for  mini-computers  were  about  32,000 
characters  with  a  few  allowing  twice  as  much. 

In  addition  to  core  considerations,  mini-computers 
typically  allowed  limited  mignitudes  in  the  number 
representations  in  memory.  For  example,  a  12-bit  computer 
can  represent  at  most  -1095  (or  ±2047).  Using  two 
computer  words  to  increase  accuracy  consumes  core  twice 
as  fast  and  involves  much  slower  execution  to  do  simple 
ari thmet ic. 


Therefore,  a  class  of  computers  exemplified  by  the 
CDC  3300  and  the  SDS  940  were  chosen  to  be  a  practical 


minimum  for  the  future  installation  of  the  PLANIT 
system  then  being  designed.  These  computers  held 
numbers  ot  the  magnitude  ±8,388,607,  or  nearly 
seven  full  signed  decimal  digits.  In  addition, 
these  word  sizes  would  permit  the  addressing  of 
core  in  the  amount  that  was  projected  to  be  needed. 

So  PLANIT  was  programmed  under  the  assumption  that 
data  could  be  manipulated  whose  magnitude  did  not 
exceed  2-v<,  nearly  seven  decimal  digits. 

PLANIT  was  also  designed  and  programmed  in  a 
completely  modular  fashion  so  that  the  overlaying 
configuration  could  readily  be  adapted  to  fit  what¬ 
ever  environment  was  presented.  However,  it  was 
known  that  configurations  of  fewer  and  larger 
segments  of  program  would  execute  much  more  rapidly 
than  many  smaller  ones,  and  it  was  assumed  that  there 
would  he  a  lower  practical  limit  that  would  be  much 
different  than  the  lower  real  limit,  namely  that 
PLANIT  could  be  cut  into  such  small  pieces  that 
execution  delays  would  be  intolerable.  That  assump¬ 
tion  is  probably  still  true  in  that  no  known  hard¬ 
ware  is  currently  available  which  would  execute 
Pi.ASTT  with  reasonable  response  time  if  it  were  cut 
up  as  finely  as  possible. 

However,  AR1  demonstrated  through  its  PLANIT 
installation  on  the  DITTOS  3300  that  PLANIT  could 
bo  run  In  less  core  than  earlier  thought  and  still 
maintain  acceptable  interaction  rates  with  several 
users.  The  PEVTOS  computer  had  the  required  word 
size  but  was  short  on  available  core  due  to  the 
tactical  operating  system  it  was  running.  So  PLANIT 
ran  in  the  equivalent  of  about  72,000  characters  of 
core,  or  about  28T>  of  the  amount  which  had  been  esti¬ 
mated  for  an  operational  system,  or  little  over  half 
of  the  projected  bare  minimum. 

Now,  enter  a  new  class  of  mini-computers.  With 
Large  Scale  Integration  and  MOS  chips,  new  tabletop 
computers  became  commercially  available  that  were 
lit  tit'  larger  physically  than  the  POP  8  variety  but 
contained  electronic  sophistication  formerly  found 
only  in  the  medium  and  large  scale  computers.  The 
Digital  Equipment  Corporation's  PDP  11  computer  is 
typical  ot  this  class.  Although  word  sizes  were 
still  lacking  (16  bits  compared  to  PLANIT's  required 
24  bits),  double  word  addressing  instructions  were 
making  it  possible  to  concatenate  two  words  into  an 
effective  32-bit  word  length  with  very  reasonable 
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execution  efficiency,  and  addressing  hardware  such  as 
Memory  Management  was  making  possible  core  sizes  up 
to  248,000  characters. 

With  these  new  hardware  advances,  and  having 
determined  that  PLANIT  could  operate  satisfactorily 
in  smaller  amounts  of  core  than  first  projected,  ARI 
undertook  to  establish  the  feasibility  of  installing 
PLANIT  on  a  POP  11,  chosen  because  it  was  representative 
of  its  class  and  one  frequently  found  at  Army  sites. 


Choosing  Th e  Target  POP  11  For  Installation  Of  PLANIT 


Rather  than  being  a  single  computer,  the  PDP  11 
is  a  family  of  computers,  from  the  PDP  11/03  to  the 
PDP  11/70.  Of  course,  ail  basically  have  the  same 
hardware  architecture  and  are  upward  compatible  through 
the  various  models.  But  there  are  also  many  variations, 
particularly  with  regard  to  their  ability  to  provide 
the  services  formerly  reserved  to  larger  computers. 

For  example,  until  recently  the  RSX-11D  Real-time 
Multiprocessing  Operating  System  required  at  least 
a  PDP  11/40  plus  several  hardware  options,  with  the 
PDP  11/45  needed  for  other  software  applications. 

Other  operating  systems  such  as  the  RT-11  run  on  the 
lower  numbered  computer  models  such  as  the  PDP  11/04, 
11/05,  11/10,  etc.  Newer  models  are  being  introduced 
such  as  the  PDP  11/34  which  provide  capabilities 
formerly  found  in  the  higher  numbered  models. 

Thus,  it  became  a  challenge  to  find  the  combina¬ 
tion  of  the  most  economical  model  with  the  fewest 
necessary  extra  options  that  might  have  a  chance  of 
running  PLANIT.  Some  of  the  considerations  were: 

•  Core  size 

•  Double-word  integers 

•  FORTRAN  IV  compiler 

•  Ability  to  run  an  overlaid  program 

•  Ability  to  communicate  with  multiple  user 
terminals 


•  Alternate  data  storage  on  a  suitably  fast 
disk 


Expanding  on  the  above  six  points  just  a  bit, 
minimum  core  size  was  determined  to  be  44,000  16-bit 
words  (actually  addressing  48,000  words  but  the  upper 
4,000  words  on  a  PDP  11  are  always  reserved  for  device 
addressing).  Considering  the  core  range  of  8,000  to 
124,000  words,  that  figure  was  chosen  out  of  consider¬ 
ation  of  several  factors: 

•  The  largest  user  program  that  can  be  task- 
built  on  a  PDP  11  is  32,000  words,  deter¬ 
mined  by  the  addressing  limit  of  the  16-bit 
word.  The  UNIX  operating  system,  developed 
by  the  Bell  Labs  for  the  PDP  11  will  handle 
a  user  program  twice  that  size,  but  it  was 
felt  that  standard  vender-supplied  software 
should  be  used  if  at  all  possible.  The 
additional  12,000  words  are  adequate  to 
run  the  RSX-11D  operating  system  utilities, 
the  choice  of  which  resulted  from  other 
considerations,  below. 

•  Double-word  integers  were  needed  to  handle 
PLA.NIT’s  larger  numbers,  and  these  were 
available  only  in  the  PDP  ll's  FORTRAN  IV 
PLUS  compiler,  and  this  in  turn  needed  the 
PSX  operating  system,  the  Extended  Arithmetic 
option  and  the  Floating  Point  Processor 
option.  The  Memory  Management  option  was 
also  needed  to  handle  the  addressing  of  core 
above  32,000  words.  The  PDP  11/40  or  11/45 
was  needed  to  accomodate  the  necessary 
configuration  (actually  there  is  little 
practical  difference  between  the  two  with 
all  of  the  above  options  in  place).  While 

it  is  true  that  there  are  other  ways  to  get 
double-word  integers  on  the  PDP  11  beside 
the  FORTRAN  IV  PLUS  compiler  with  the 
Floating  Point  Processor,  these  all  would 
have  added  significantly  to  the  installation 
time  where  it  was  not  yet  known  whether  the 
installation  would  even  be  successful.  There¬ 
fore,  the  more  sure  alternative  was  chosen. 

•  The  RSX  operating  system  also  provided  the 
necessary  Object  Time  System  utilities  for 
most  easily  serving  the  needs  of  the  real 
time  interaction  of  the  terminals,  as  well 
as  the  overlay  structure  of  the  PLANIT 
system. 
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If  PLANIT  was  to  run  on  the  PDP  11  using  vender 
supplied  software,  it  was  clear  that  it  would  have  to 
run  in  32,000  words  (i.e.  the  equivalent  of  64,000 
characters) .  This  would  be  even  less  than  the  DEVTOS 
installation  before  the  loss  due  to  double-word  integers 
was  subtracted.  To  say  that  the  prospect  of  success 
for  the  installation  at  that  time  was  less  than  certain 
is  an  understatement. 

It  should  be  noted  that  just  having  the  core 
available  is  not  enough.  There  must  also  be  the  means 
for  shuttling  program  overlays  through  the  core  plus 
the  hardware  for  performing  double-word  arithmetic. 

All  of  these  factors  seemed  to  point  to  the  RSX 
operating  system,  where  the  44,000  word  core  seemed 
to  be  a  reasonable  practical  minimum  for  the  RSX-11M 
and  in  fact  is  the  minimum  in  the  case  of  the  RSX-11D 
operating  system. 

The  44,000  word  core  is  not  generally  a  limiting 
factor  for  PLANIT  installations  for  a  large  number 
of  extant  PDP  11  sites.  Nearly  all  of  the  several 
sites  that  were  contacted  had  at  least  that  much  and 
usually  more.  Additional  core  is  one  of  the  lesser 
expensive  options  for  the  PDP  11.  It  would  pi*obably 
have  been  acceptable  to  assume  even  more  core  were  it 
not  for  the  32,000-word  limit  imposed  on  standard 
compiled  user  programs.  To  exceed  that  limit  would 
impose  more  difficulty  on  future  PDP  11  installations 
since  each  would  have  to  implement  some  non-standard 
core-extending  programming  technique. 

Having  chosen  the  RSX  operating  system  in  44,000 
words  of  core  with  the  FORTRAN  IV  PLUS  compiler,  the 
problem  of  integer  size  was  solved.  The  FORTRAN  IV 
PLUS  compiler  has  an  "14"  switch  which,  if  set  "on", 
will  cause  all  integers  to  be  executed  in  double  word 
fashion.  However,  sufficient  core  would  then  be 
critical  since  double  word  integers  not  only  require 
twice  as  much  data  space  but  also  require  extra  program 
instructions  to  execute  properly.  In  oi’der  to  see 
how  much  difference  it  did  make,  a  segment  of  PLANIT 
was  compiled  both  ways,  with  the  "14"  switch  off  and  on. 
Then  the  compile  maps  of  the  two  were  compared.  With 
the  "14"  switch  "on",  the  program  size  expanded  42%  and 
the  pi'ogram  data  expanded  89%.  Thus  it  is  obvious  that 
if  the  double-word  requirement  could  be  removed,  a 
significant  amount  of  core  could  be  put  to  more  productive 
use.  More  will  be  said  in  this  regard  later. 


The  final  consideration  in  choosing  an  appropriate 
PDP  11  was  to  insure  that  it  had  a  suitable  disk. 


_ ■'■i. 


•  Any  of  the  standard  disks  (other  than  the 
relatively  slow  "floppy  disk")  was  thought 
to  be  adequate,  with  the  fixed-head  disks 
being  somewhat  faster  than  t ho  cartridge 
disks.  However,  even  the  70  mil  1 l-soeond 
access  time  of  the  RK05  cartridge  disk 
could  bo  tolerated,  giving  the  advantage 
of  removable  cartridges  where  this  is  often 
the  most  convenient  way  of  taking  the  data 
ovi  t  of  t  ho  Pl)P  1 1  system  (not  too  many 
have  standard  magnetic  tape  units  attached). 
As  a  matter  of  fact,  the  system  used  In  the 
installation  did  have  RKOh  disks.  If  t ho 
same  code  was  used  w i t h  the  faster  fixed- 
head  disks,  t ho  responsiveness  of  the  POP  11 
PI.  AN  IT  would  Improve. 

Therefore,  the  search  was  on  for  a  PUP  11/40  or 
POP  11  U>  running  RSX-llM  or  USX- 111',  having  the 
FORTRAN  IV  PI. US  compiler  with  the  additional  Floating 
Point  Processor  option  that  It  required.  It  Is  a 
matter  of  record  l it  the  monthly  reports  that  it  took 
i  \  months  to  find  such  a  configuration  on  which  time 
could  be  made  available,  and  then  t he  site  lacked  the 
FORTRAN  IV  PI. US  compiler  but  was  willing  t  o  purchase 
the  software  license  in  order  to  sell  the  time.  The 
effort  expended  in  the  search  Is  Incidental  to  the 
project  report  even  though  It  had  profound  effect  on 
the  scheduling  and  budget  of  the  project.  However, 
the  difficulty  encountered  in  finding  such  a  system 
does  say  something  about  future  changes  that  might 
be  made  In  PUP  11  installations  of  PLAN IT  in  order 
to  make  them  adaptable  t o  a  more  readily  available 
configuration  of  the  POP  11. 


As  it 
the  POP  11 
that  those 
engaged  in 
are  not  in 
rise.  This 


turns  out,  while  USX  configurations  o f 
can  he  found  relatively  easily.  It  seems 
who  need  that  configuration  are  generally 
work  of  such  a  special  nature  that  they 
a  position  to  make  time  available  to  anyone 
is  not  to  say  that  POP  It  time  Is  hard  to 


find.  On  the  cent  rary ,  '  t  line  on  t he  POP  11  RSTS  K 
time-sharing  system  seems  to  he  available  everywhere. 
Most  universities  who  run  the  POP  ll  seem  t o  run  that 
operating  system.  Several  eommerelal  time-sharing 
vendors  also  market  RSTS/K  time.  RSTS  K  will  run 
overlaid  programs  of  sufficient  si  go  and  has  a 


FORTRAN  IV  compiler,  but  unfortunately,  that 
does  not  accomodate  double-word  Integers  and 
opornt  lug  system  does  not  aeeept  the  FORTRAN 


comp  I  1 er 
the  RSTS/K 
IV  PI. OS 
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compiler.  It  is  this  combination  of  circumstances  that 
lead  to  the  suggestion  to  be  made  a  little  later  about 
modifying  PLANIT  to  eliminate  double-word  requirements 
on  16-bit  computers.  Given  that  change,  the  number  of 
PDP  11  installations  which  could  run  PLANIT  would 
increase  dramatically. 


Installation  Experience  On  The  PDP  11 


Arrangements  were  made  to  use  a  PDP  11/45  at  the 
Center  for  Computer  Based  Education  located  on  the 
campus  of  the  University  of  California  at  Los  Angeles. 
Two  weeks  o  required  on  site  to  complete  the  instal¬ 
lation.  O  BE  provided  expert  system  assistance  which 
was  absolutely  necessary  to  the  success  of  the  instal¬ 
lation. 


It  is  also  worth  mentioning  at  this  point  that 
ARI's  foresight  in  allowing  for  a  failure  to  install 
the  system  to  be  an  acceptable  alternative  might 
easily  have  made  the  difference  whether  the  project 
was  ever  completed.  Aside  from  any  reluctance  the 
project  team  may  have  had  to  undertake  the  project  if 
a  successful  installation  was  required,  it  also  affected 
arrangements  with  the  computer  site.  The  CCBE  personnel 
were  sufficiently  experienced  to  recognize  the  project 
as  having  a  relatively  high  risk  of  failure  and  they 
would  not  have  accepted  the  arrangements  for  use  of 
the  computer  unless  a  possible  failure  was  acceptable. 

The  PLANIT  Generator  program  was  not  installed 
on  the  PDP  11  although  it  was  the  intention  to  do  so. 
Even  though  there  was  no  contractual  reasons  to  install 
the  Generator  program,  that  seemed  at  first  to  be  the 
most  reasonable  way  to  proceed.  However,  the  Generator 
program  is  not  as  modular  as  PLANIT  and  would  not 
compile  because  of  its  size.  Not  that  the  Generator 
program  would  exceed  the  available  32,000  words  of 
core,  but  the  FORTRAN  compiler  will  only  compile 
chunks  of  about  1,400  lines  of  code  (approximately 
6,000-8,000  words  of  core)  at  a  time  and  these  compiled 
pieces  are  then  put  through  a  Task  Builder  on  the  PDP  11 
in  order  to  utilize  the  core  as  fully  as  desired.  So, 
rather  than  spend  extra  time  making  the  Generator 
program  fit  onto  the  PDP  11,  it  was  installed  on  the 
PDP  10  computer  which  is  also  running  at  the  same  site. 
The  PDP  10  was  then  used  to  generate  the  PLANIT  code 
(in  FORTRAN)  for  compilation  on  the  PDP  11.  This 
procedure  worked  very  smoothly. 


Having  workod  Into  the  second  week  and  finally 
having  all  tho  pieces  for  PLANIT  including  the  twenty- 
five  overlays,  the  MIOP,  LDBYTE  and  SBYTE  interface 
programs  ready  to  Task  Build,  it  was  then  discovered 
that  wo  exceeded  available  core  by  more  than  2,000 
words.  At  that  point,  failure  appeared  to  be  a  very 
real  alternative.  However,  it  was  discovered  that 
the  pieces  could  be  recompiled  without  a  debugging 
"traco"  option,  effecting  a  significant  reduction  in 
tho  size  of  the  compiled  modules.  This  meant  that 
tho  PDP  It  system  would  givo  virtually  no  cross- 
referencing  kind  of  help  in  tho  event  of  an  eri*or  but 
wo  were  willing  to  live  with  that,  especially  since 
the  PLANT T  code  is  relatively  dependable. 

Without  the  "trace"  option,  the  pieces  all  fit 
into  the  available  core.  The  statistics  of  the  core 
map  follow: 


•  Total  core  available  (for  PLANIT)  32,768  (words) 


Common  Data  8,084 
MIOP  1,974 
LDBYTE  &  SBYTE  48 
Main  Program  4,751 
Overlay  Space  6,498 
Additional  PDP  11  utilities  11,056 
Total  core  used  32,411 


Tt  appears  that  PLANIT  Just  barely  squeezed  in. 
Ilowovor,  it  actually  fit  into  30,464  words  of  core  and 
the  main  progrnm  was  later  enlarged  by  adding  some 
critical  code  from  one  of  the  overlays  to  speed  up 
the  execution.  While  tho  smaller  version  was  running, 
wo  experimented  with  another  (very  small)  PDP  11 
program  running  concurrently  and  found  that  it  did 
in  fact  run  satisfactorily. 

This  configuration  makes  PLANIT  ovei'lay  more  often 
than  any  other  current  installation.  Other  measures 
also  wore  required  to  keep  the  size  down,  such  as: 

•  Restricting  tho  number  of  frames  in  a  PLANIT 
lesson  to  50  (instead  of  the  usunl  100) 


•  Reducing  the  number  of  initial  characters 
kept  in  dictionary  representations  of  names 
to  four  (from  the  usual  eight  or  more) 

•  Reducing  Calc  work  space  to  less  than  usual 

However,  despite  these  reductions,  overy  PLANIT 
system  function  is  operational  on  the  PDP  11. 

Four  terminals  were  active  on  the  PLANIT  system 
and  all  operated  nonnally.  Thei'e  were  three  of  us 
available  to  provide  concurrent  interaction.  While 
there  was  not  opportunity  to  gather  accurate  response 
time  data  over  a  range  of  activities,  response  times 
that  were  observed  varied  from  one  to  five  seconds  for 
replies  which  are  usually  immediate  (e.g.  lesson  building) 
up  to  twenty  u*  more  seconds  for  operations  whore  some 
delay  is  normal  (e.g.  finishing  lesson  execution). 

Response  delays  were  usually  small  enough  to  be  tolerable. 


Improving  The  Performance  Of  PLANIT  On  The  PDP  11 


It  was  already  mentioned  earlier  that,  where  a 
choice  existed,  the  more  complex  installation  proce¬ 
dures  were  avoided  since  the  first  priority  was  to 
determine  whether  PLANIT  would  fit  into  the  PDP  11. 

It  would  be  poor  judgment  to  spend  more  than  an  abso¬ 
lute  minimum  to  find  that  out.  Now  that  the  project 
has  established  that  PLANIT  will  run  (in  face,  does  run) 
on  a  PDP  11,  there  are  several  endeavors  which  could  be 
undertaken  to  make  it  run  faster  and  even  to  restore 
some  or  all  of  the  space  that  was  reduced.  Three 
possibilities  might  be  considered,  each  of  which  would 
save  some  core  space  which  could  be  reallocated  to 
improve  the  operation  of  PLANIT:  1)  reduce  the  24-bit 
minimum  word  size  in  PLANIT  to  16  bits,  2)  modify  MIOP 
to  eliminate  as  many  of  the  PDP  11  utilities  as  possible, 
and  3)  move  some  program  functions  into  the  next 
32,000-word  partition  of  core.  These  throe  possibilities 
will  now  be  considered  in  more  detail. 

First,  the  reduction  of  the  24-bit  requirement 
to  16  bits  would  have  made  a  significant  difference  in 
the  space  used  by  the  Common  data  and  by  the  program 
code.  It  was  mentioned  earlier  that  compile!*  tests 
indicated  what  the  savings  would  be.  Double  word 
compiling  caused  the  data  to  expand  by  89%  while  the 
program  code  expanded  by  42%. 


The  89%  expansion  figure  for  the  data  was  due  to 
the  fact  that  not  all  of  the  data  items  were  integer. 
If  they  had  been,  the  expansion  would  have  been  100%. 
However,  no  change  occurs  in  the  space  needed  for 
real  (floating  point)  data  when  the  precision  of  the 
integer  data  is  changed. 

The  42%  expansion  figure  for  the  program  code  is 
due  primarily  to  the  additional  instructions  which 
become  necessary  to  process  each  of  the  two  words 
that  make  up  the  integer  data  item.  Since  most  of 
the  program  involves  integer  data,  much  of  the  code 
is  affected. 

In  the  current  PDP  11  PLANIT  installation,  there 
are  8,084  words  of  data  and  11,249  words  of  PLANIT 
code  which  make  reference  to  it.  Applying  the  above 
percentages,  8,084  is  an  89%  expansion  of  4,278 
(8,084/1.89=4,278)  and  11,249  is  a  42%  expansion  of 
7,921  (11,249/1.42=7,921).  Therefore,  if  single  words 
were  used  for  integer  data,  the  savings  would  be 
approximately  7,134  words  ( (8 , 084-4 , 278)+(ll , 249- 
7 , 921)=7 , 134) .  Note  that  7,134  words  represents  22% 
of  the  total  size  of  the  system,  and  is  larger  than 
MIOP  or  any  one  piece  of  the  PLANIT  code.  That  space 
could  be  reallocated  to  provide  more  lesson  space  as 
well  as  to  put  more  of  the  frequently  used  sections 
of  code  into  the  main  program  where  it  would  execute 
faster  (because  no  overlaying  would  be  necessary). 

This  option  alone  could  restore  all  of  the  usual 
lesson  space  to  PLANIT  and  improve  response  time  a 
little,  too. 

In  order  to  incorporate  this  option,  all  of  the 
present  PLANIT  code  would  need  to  be  checked  for  use 
of  integer  values  in  excess  of  ±32,767,  and  where 
found,  different  algorithms  would  have  to  be  written 
to  reduce  the  size  of  the  numbers  used.  This  would  be 
a  big  task  but  it  would  yield  a  sizeable  benefit 
(22%  savings  of  core) . 

Since  the  24-bit  minimum  could  have  been  avoided 
when  the  system  was  originally  coded,  one  might  wonder 
why  now  choose  16  bits?  Why  not  less  and  avoid  a 
similar  mistake  later?  The  next  smaller  size  which 
would  make  any  sense  in  the  computer  industry  would  be 
12  bits.  This  would  impose  a  limit  on  the  integer 
size  to  ±2,047.  It  would  not  be  reasonable  to  impose 
such  a  small  limit  on  the  coding.  Indeed,  that  small 
a  limit  would  cause  the  programming  algorithms  them¬ 
selves  to  mushroom  in  size,  defeating  the  purpose. 


There  will  necessarily  be  some  expansion  in  coding 
when  different  ways  are  devised  for  processing  numbers 
whose  size  exceeds  the  16-bit  limit.  However,  16  bits 
provides  four  full  digits  of  accuracy  which  will  be 
adequate  in  most  cases,  and  will  hold  at  least  half 
of  the  number  in  the  remaining  cases.  Also,  in  order 
to  avoid  penalizing  larger  sites  which  have  the  required 
word  size,  the  Generator  language  permits  alternate 
coding  such  that  appropriate  program  statements  are 
automatically  selected  according  to  the  parameters 
which  are  used  to  describe  the  target  computer.  Since 
the  number  of  bits  in  a  word  is  already  a  parameter, 
the  new  coding  which  accomodates  to  16-bit  words 
could  be  selected  only  if  that  parameter  value  was 
less  than  24. 

The  second  improvement  which  was  suggested  was 
to  improve  MIOP  and  thus  eliminate  some  of  the  PDP  11 
utilities.  Notice  that  the  largest  single  segment 
of  the  core  map  of  PLANIT  on  the  PDP  11  was  the 
collection  of  utility  programs.  These  accounted 
for  34%  (11,056/32,411-34%)  of  the  total.  Much  of 
this  is  a  collection  of  pieces  belonging  to  the  PDP  11 
Object-Time  System.  These  software  utilities  provide 
resources  for  real-time  operations  of  one  sort  or 
another.  It  is  likely  that  PLANIT  does  not  use  (or 
need  not  use)  at  least  half  of  these  utilities.  Much 
of  what  they  do  surely  is  redundant  with  what  PLANIT 
is  already  doing.  For  example,  it  is  not  necessary 
that  the  terminals  be  queued  for  PLANIT,  that  is  already 
being  done. 

The  task  would  be  to  become  familiar  enough  with 
each  of  the  components  of  the  system  utilities  so 
that  their  use  could  be  bypassed  and  they  could  then 
be  eliminated  from  core.  There  is  good  reason  to 
believe  that  5,000  or  more  words  could  be  saved  in 
this  fashion  and  reallocated  as  suggested  above. 

The  above  option  suggested  that  the  present  program 
and  data  could  be  reduced  to  7,921+4,278=12,199  words, 
saving  7,134  words.  If  another  5,000  words  could  be 
saved  from  the  utilities,  that  amounts  to  a  total  of 
12,134  words  that  could  be  reallocated  back  into 
the  PDP  11  PLANIT,  effectively  doubling  all  of  the 
present  PLANIT  capability  on  the  PDP  11.  These  are  not 
unreasonable  expectations. 

The  third  (and  final)  improvement  which  was  sug¬ 
gested  above  is  the  moving  of  some  of  the  functions 
into  the  upper  regions  of  core,  above  32,768  addresses. 
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This  may  l>o  the  most  questionable  of  the  improvements 
simply  because  it  would  involve  some  unconventional 
coding.  In  effect,  a  discreet  part  of  the  support 
package  for  PLAN  IT  (such  as  terminal  processing)  would 
bo  removed  and  made  into  a  separate  program  which  then 
would  run  in  the  higher  partition.  There  are  ways  that 
this  new  program  and  the  remaining  PLANIT  program  can 
be  made  to  exchange  data.  Therefore,  the  support 
progr;un  ii  high  core  would  do  its  work  independently 
of  PL.4NIT  and,  when  finished,  would  pass  the  results 
over  to  PI.ANIT,  and  PLANIT  would  do  likewise.  The 
savings  would  be  effected  by  the  fact  that  another 
part  of  tl  o  32,000  word  program  space  would  then  be 
made  available  for  more  productive  use  by  PLANIT.  It 
is  too  dilficult  to  project  how  much  that  might  be  but 
it  could  1  e  several  thousand  words. 

Anotl  or  possibility  would  be  to  use  high  core 
to  queue  PLANIT  overlays  so  they  could  be  retrieved 
more  rapidly  than  from  disk.  Again  the  coding  would 
be  unconventional  but  the  increase  in  execution 
efficiency  could  be  significant.  This  option  would 
probably  mean  that  at  least  64,000  words  of  core 
would  be  needed  on  the  PDP  11. 


Con cl  iding  Komarks  For  The  PDP  11  Installation  Effort 


'’he  project  has  established  the  feasibility  of 
installing  PLANIT  on  the  PDP  11.  In  addition,  it 
appears  quite  certain  that  the  installation  could  be 
optimized  to  both  run  much  faster  and  utilize  more 
common  PDP  11  hardware/software  configurations. 

It  now  appears  to  be  quite  reasonable  to  run 
PLANIT  on  model  numbers  as  low  as  the  PDP  11/34  and 
perhaps  lower.  Also,  with  the  benefit  of  the  proposed 
changes,  i he  FORTRAN  IV  compiler  could  be  used  in 
place  of  the  FORTRAN  IV  PLUS  compiler,  and  it  may  be 
possible  to  run  PLANIT  without  the  Floating  Point 
Processor  hardware  with  little  degredation  in  response 
t  ime. 


j  f  these  options  are  implemented,  then  PLANIT 
ought  to  execute  very  satisfactorily  on  the  "average" 
PDP  11  hardware  configuration. 


DE\  ELOPMENT  OF  THE  PORTABLE  QUERY  SYSTEM 


The  Portable  Query  System  is  an  interactive  infor¬ 
mation  retrieval  component  of  a  data  management  system. 

The  primary  purpose  of  the  development  of  PQS  was 
to  test  the  application  of  the  transportable  coding 
procedures  and  the  application  of  PLANIT's  operating 
system  to  non-PLANIT  software.  Therefore,  the  immediate 
purpose  for  this  software,  which  is  nearing  completion 
as  of  this  writing,  is  a  successful  demonstration  of 
on-line  queries  from  a  data  base  supplied  by  ARI. 

Consistent  with  the  purpose  for  the  PQS  software, 
this  report  will  analyze  the  application  of  the  t rans- 
portablo  coding  procedures  rather  than  discussing  the 
design  of  the  Query  system.  The  reader  who  may  be 
interested  in  further  information  on  the  Query  system 
will  find  a  statement  of  the  system  specifications  in 
Appendix  A  and  a  PQS  User's  Manual  in  Appendix  B. 

There  are  three  main  topics  of  interest  in  regard 
to  the  transportable  coding  procedures,  each  of  which 
will  be  the  subject  of  one  of  the  following  sections. 


Application  Of  Transportable  Coding  To  PQS 


Transportable  coding  procedures  were  devised 
several  years  ago  in  connection  with  the  development 
of  the  PLAN IT  software.  It  amounted  to  an  exhaustive 
examination  of  each  of  the  elements  of  conventional 
computer  programming  which  tend  to  link  the  resulting 
software  to  the  specific  kind  of  computer  for  which 
it  was  written,  even  occasionally  limiting  the  execu¬ 
tion  to  one  specific  machine. 

Machine  dependencies  are  typically  introduced 
into  a  computer  program  from  several  sources,  including 
hardware  architecture,  character  sets,  instruction 
repertoire,  input/output  device  characteristics  and 
operating  systems.  Any  one  of  the  above  can  account 
for  machine  dependencies  in  software,  and  more  often 
than  not,  all  of  them  influence  the  software. 


Conversion  of  software  from  one  computer  to 
another  is  rarely  a  trivial  task.  It  is  common  to 
spend  more  than  half  of  the  original  effort  to  accom¬ 
plish  tho  conversion. 

The  PLANIT  development  effort  determined  to  avoid 
this  high  program  conversion  cost  by  finding  an  accept 
able  commonality  among  computers  for  the  purpose  of 
writing  software  code  which  could  run  on  most  of  them. 
This  involved  three  essential  elements: 

•  Determining  what  software  coding  conventions 
would  be  acceptable  on  all  target  machines 

•  Developing  a  method  for  automatically 
modifying  the  code  for  additional  hardware 
differences  where  commonality  was  impractical 

•  Defining  a  clear  and  comprehensive  set  of 
procedures  for  installing  the  completed 
system  on  any  computer  where  the  installation 
interface  would  be  functionally  identical 

on  all  of  them. 

There  are  several  subgoals  which  were  of  equal 
import? nco  if  the  method  was  to  have  any  chance  of 
acceptance,  such  as  not  compromising  the  capability 
or  efficiency  of  the  target  hardware.  One  cannot 
simply  reduce  all  machines  to  their  lowest  common 
denominator  since  the  result  would  probably  not  be 
adequate  and  certainly  not  appealing  to  any  programmer 

One  of  the  early  decisions  was  to  make  use  of 
some  higher  level  language  in  the  transport  process. 
Compiler  programs  for  these  languages  are  already 
considered  to  be  an  absolutely  essential  part  of 
nearly  any  computer  package,  and  these  compilers 
have  done  much  to  make  many  of  the  machine  differences 
transparent  to  the  user.  For  example,  simple  arith¬ 
metic  expressions  look  nearly  alike  in  many  different 
lanj  uages  and  on  many  different  computers  even  though 
the  machine  instruction  sequences  into  which  they  get 
comj  iled  w’ill  often  be  quite  different. 

FORTRAN  was  chosen  to  be  the  most  commonly  used 
higl  ter  level  language  for  the  mediating  process  of 
tho  transpoi't  of  the  PI.ANIT  program.  The  reason  for 
this  choice  was  because  of  tho  wide  availability  of 
FORTRAN  compilers,  not  because  it  was  any  more  suit¬ 
able.  The  procedure  is  not  entirely  dependent  on  the 
use  of  FORTRAN  but  has  had  only  one  case  so  fax*  where 


FORTRAN  was  not  the  appropriate  choice,  the  case  of  the 
TACFIRE  system  on  the  ANGYK-12  machine,  where  TACPOL 
was  used  instead. 

Having  determined  through  several  prior  case 
studies  that  PLANIT  was  being  installed  on  a  variety 
of  computers  pretty  much  as  predicted,  ARI  became 
interested  in  wider  applications  for  the  method.  Since 
PLANIT  is  a  very  large  and  complex  software  system,  it 
already  contains  many  coding  examples  which  have  features 
in  common  with  nearly  any  programming  algorithm  one  can 
think  of.  Thus,  of  all  the  typical  problems  that  one 
might  expect  in  the  design  of  this  new  software,  the 
constraints  necessary  to  maintain  transportability  never 
once  entered  into  the  problem  nor  were  any  of  the  design 
problems  co  founded  by  the  need  to  meet  these  standards. 
The  situations  had  all  been  met  in  some  form  in  earlier 
experiences  with  PLANIT. 

Since  issues  involving  transport  were  not  a  parti¬ 
cular  concern,  there  was  some  interest  in  comparing 
coding  efficiencies.  Although  there  was  no  opportunity 
to  make  rigorous  observations,  it  appeared  that  the 
coding  effort  may  have  been  more  difficult  by  as  much 
as  ten  percent  owing  to  the  need  to  maintain  standards 
for  transport.  However,  given  comparable  experience, 
the  differences  might  be  reduced. 

One  aspect  of  this  coding  method  soon  becomes  very 
clear,  machine  characteristics  play  no  part  in  defining 
the  coding  task.  There  are  many  examples  where  program 
specifications  undergo  slight  changes  during  coding  due 
to  accomodations  to  certain  hardware  features.  Such  is 
not  the  case  for  transportable  coding  for,  if  any  par¬ 
ticular  machine  feature  were  allowed  to  influence  the 
task,  the  transportability  would  certainly  be  compro¬ 
mised. 

The  reader  might  well  be  wondering  by  now  just 
when  this  transportable  coding  method  will  be  explained. 
Unfortunately,  such  an  explanation  would  go  beyond  the 
resources  for  this  report.  However,  an  experienced 
programmer  would  probably  find  little  that  was  novel. 
Rather,  the  method  consists  of  a  collection  of  known 
procedures  for  improving  the  transportability  of 
programs,  such  as  character  mapping,  simplistic  data 
organization,  execution-time  data  initialization,  table- 
driven  input  and  output,  etc.  What  distinguishes  this 
method  is  that  a  carefully  chosen  set  of  such  procedures 
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were  assembled  into  a  comprehensive  "language"  such 
that  the  programmer  follows  specific  guidelines  in  the 
coding  effort.  Therefore  the  programmer  does  not  have 
to  be  overly  concerned  about  the  matters  of  transport 
so  long  as  the  method  is  followed. 

Those  who  seem  to  find  the  most  difficulty  with  the 
method  ave  those  who  have  had  prolonged  experience  with 
a  particular  kind  of  computer.  They  tend  to  think  in 
terms  of  the  architecture  of  that  machine  instead  of 
the  framework  of  the  language.  A  typical  orientation 
time  for  such  an  experienced  programmer  to  this  method 
is  about  six  months  during  which  three  typical  phases 
are  traversed:  disbelief  (it  can't  work),  unlearning 
and  relearning.  In  some  respects  it  is  easier  to  train 
one  who  is  new  to  the  business,  or  at  least  has  not 
become  entrenched  in  a  particular  kind  of  hardware.  One 
makes  fewer  coding  errors  if  certain  characteristics  of 
the  machine  are  not  known  (e.g.  bits  or  bytes  in  a  computer 
word,  character  set  collation  sequence,  etc.). 

Based  on  the  experiences  with  the  method,  first  with 
PLANIT,  and  now  with  the  Query  system,  there  appear  to 
be  no  known  drawbacks  which  would  preclude  further 
experiments  in  other  applications. 


Appl-1  cation  Of  The  MAGIC  Opei’ating  System 


A  computer  operating  system  logically  integrates 
a  user's  program  into  the  operating  environment  of 
the  computer,  scheduling  and  supervising  its  execution, 
providing  communication  with  peripheral  devices,  etc. 

The  fact  that  PLANIT  included  an  operating  system  was 
never  in  question  because  it  couldn't  function  without 
it.  However,  PLANIT's  operating  system  was  not  a 
separate,  distinguishable  entity. 

Part  of  the  current  effort  was  to  extract  from 
PLANIT  the  part  that  could  be  identified  as  its  operating 
system,  and  vise  that  as  the  starting  point  for  the 
development  of  the  Query  demonstration  system.  Since 
PLANIT  is  a  time-sharing  system,  that  also  characterizes 
its  operating  system.  That  which  was  extracted  fv'om 
PLANIT  was  called  MAGIC  (Machine  Adaptable  Generated 
Interactive  Console  system). 


The  MAGIC  system  is  of  interest  not  only  because 
it  controls  the  Query  system  but  also  because  of  its 
potential  use  in  other  transportable  program  environ¬ 
ments.  Essentially,  it  consists  of  a  set  of  procedures 
for  managing  the  data  communication  between  each  of  the 
peripheral  devices,  and  allocating  the  resources  of 
those  devices  in  an  orderly  manner  to  each  of  the  users. 

It  was  not  particularly  difficult  to  extract 
MAGIC  from  PLA.NIT  and  to  instead  put  it  in  control 
of  the  Query  system.  A  brief  examination  of  the 
two  systems,  PLANIT  and  PQS  (Query),  will  quickly 
show  the  code  that  is  common  to  both,  which  has  been 
given  the  name,  MAGIC.  It  was  also  used  for  the  PLANIT 
Interface  Test  program  which  will  be  described  latex'. 

No  additional  difficulty  was  encountered.  Time-shai'ing 
systems  have  typically  been  some  of  the  more  delicate 
to  make  work  propei'ly  and  it  some  sense  of  achievement 
to  see  it  so  easily  adapted  to  othex-  applications 
without  incui-ring  problems. 

However,  as  an  operating  system,  MAGIC  has  one 
serious  flaw.  It  necessarily  takes  on  some  of  the 
characteristics  of  the  user  programs  it  supervises. 

The  MAGIC  system  was  nevei'  developed  as  a  stand¬ 
alone  operating  system.  When  used  with  PLANIT,  it 
has  some  PLANIT  data  structured  within  it.  When  opera¬ 
ting  with  PQS,  it  reflects  some  of  the  structure  of 
that  system.  The  reason  that  condition  is  considered 
to  be  serious  is  that  the  MAGIC  operating  system  must 
be  recompiled  fox*  each  new  application  it  conti'ols. 

This  would  be  equivalent  to  buying  some  time-sharing 
service  and  then  requiring  that  the  vender  modify  the 
system  to  accomodate  your  program.  In  oi'der  to  be 
viable  as  an  opei'ating  system,  the  MAGIC  system  will 
need  to  be  redesigned  to  become  functionally  independent 
of  the  programs  being  supervised.  Since  this  question 
is  interrelated  with  the  next  topic,  it  will  be  left 
here  and  taken  up  again. 


Communication  Among  Systems 


Interest  has  been  expressed  in  using  PQS  along 
with  PLANIT  so  that  the  PLANIT  tutorial  capabilities 
could  enhance  the  user’s  ability  to  compose  good 
query  statements.  In  fact,  the  question  of  using 


PLAN  IT  with  other  software  systems  on  the  same  computer 
has  come  up  frequently.  Using  a  generalized  "Program  X" 
to  identify  the  other  software  that  is  to  operate  with 
PLANiT,  the  question  logically  divides  itself  into  four 
separate  considerations: 


•  Is  Program  X  to  become  a  part  of  the  PLANIT 
system? 

•  Are  both  Program  X  and  PLANIT  under  the 
control  of  the  MAGIC  operating  system? 

•  Is  PLANIT  to  control  more  than  one  user? 

•  Can  Program  X  be  modified  to  suit  specific 
needs  for  communication  with  PLANIT? 


These  four  questions  will  comprise  the  outline  for 
the  discussion  regarding  the  possibility  of  communi¬ 
cation  between  PLANIT  and  other  programs. 


1 s  Program  X  To  Become  A  Part  Of  The  PLANIT  System?  This 
question  implies  that  the  code  for  the  other  program 
(.Program  X)  is  simply  added  to  the  PLANIT  code,  using 
the  sanr  data  formats,  in  effect  becoming  an  extension 
to  PLAN .  T . 


This  option  is  certainly  possible.  It  can  easily 
be  demonstrated  in  the  present  PLANIT  code.  A  capability 
now  exists  within  PLANIT  for  the  creation  and  editing  of 
card  image  files.  This  is  separate  and  distinct  from 
lesson  creation  and  editing.  In  PLANIa  that  subsystem 
is  called  EDTEXT.  It  is  functionally  separate  from 
PLANIT's  instructional  functions  other  than  its  use 
for  manipulating  decks  which  have  been  keypunched 
off-line. 

In  general,  this  option  is  no  longer  desirable. 

One  of  Vurphv’s  Laws  state  that  "a  program  will  grow 
to  occupy  all  the  space  available."  It  becomes  a 
little  difficult  to  relate  Murphy’s  Law  to  PLANIT,  at 
least  until  installation  time  in  which  case  it  may  be 
discovered  that  it  has  outgrown  the  available  space. 

PLANIT's  present  size  was  already  a  major  factor 
in  the  PDP  11  installation  effort.  There  are  critical 
needs  for  PLANIT  in  the  area  of  instruction,  such  as 
the  capability  to  display  graphics.  Therefore,  it 
would  seem  to  be  unwise  to  encumber  PLANIT  with  other, 


non-related  software  tasks.  There  can  be  some  exceptions. 
In  the  case  of  EDTEXT,  for  example,  that  subsystem  almost 
entirely  resides  on  disk  when  not  in  use.  Its  presence 
in  the  PLANIT  system  las  added  at  most  the  equivalent  of 
one  or  two  FORTRAN  statements  to  the  core-resident  code. 
Everything  else  it  uses,  including  the  dictionary  for 
its  language  syntax,  is  borrowed  from  PLANIT' s  instruc¬ 
tional  components.  Its  only  impact  on  the  system  is  in 
the  additional  overlaying  it  causes  while  being  used, 
and  since  it  is  used  so  seldom,  that,  too,  is  negligible. 

There  are  not  many  applications  like  EDTEXT  which 
could  be  added  to  PLANIT  with  so  little  impact  to  the 
system.  In  general,  one  would  assume  that  PLANIT  would 
grow  significantly  with  the  addition  of  the  new  package. 
Even  though  J 'e  communication  between  the  old  and  the 
new  (all  within  PLANIT)  could  then  be  nearly  anything 
desired,  this  does  not  seem  to  be  an  acceptable  option. 


Are  Both  Program  X  and  PLANIT  Under  The  Control  Of  The 
MAGIC  Operating  System?  This  would  seem  to  be  the 
preferrable  way  to  establish  communication  between 
PLANIT  and  some  Program  X.  Although  there  is  no  defin¬ 
ite  design  for  accomplishing  the  communication  link, 
it  should  not  be  too  difficult  to  work  out. 

The  main  objection  to  this  option  is  found  in  the 
MAGIC  operating  system  itself.  The  earlier  section 
dealt  with  the  problem  in  the  MAGIC  system,  that  of 
having  to  incorporate  some  of  the  characteristics  of 
the  program  it  moniters  within  the  compiled  code. 

This  has  two  implications,  both  unacceptable: 

•  The  MAGIC  system  must  be  modified  and  recom¬ 
piled  for  each  new  subprogram  it  supervises. 

•  "he  MAGIC  system  grows  in  size  each  time  a 
new  subprogram  is  added  to  its  repertoire. 

The  MAGIC  system  as  identified  in  PLANIT  is  slightly 
different  from  the  MAGIC  system  as  modified  for  PQS. 

If  both  PLANIT  and  PQS  were  to  run  concurrently,  the 
MAGIC  system  would  have  to  contain  supporting  elements 
for  both.  If  the  capability  to  run  yet  a  third  sub¬ 
program  was  to  be  added,  MAGIC  would  grow  again.  This 
is  an  unacceptable  trait  for  an  operating  system. 

In  order  to  make  MAGIC  a  viable  operating  system 
and  to  make  the  concurrent  running  of  subprograms  a 


good  way  to  achieve  desired  intercommunication,  MAGIC 
should  be  redesigned  to  become  an  independent  operating 
system  such  that  new  subprogram  applications  could  be 
accomodated  without  change  to  MAGIC. 

As  indicated  before,  the  part  of  PLANIT  which  is 
now  called  MAGIC  was  not  designed  to  stand  alone  as 
an  independent  operating  system.  It  was  not  difficult 
to  adapt  it  for  the  PQS  application,  but  the  adaptation 
was  no  more  independent  than  the  original. 

It  would  be  difficult  to  predict  what  all  would 
be  involved  in  producing  a  stand-alone  version  of  MAGIC. 
The  nature  of  the  task  would  bo  to  develop  a  machine 
independent,  transportable  operating  system  which  func¬ 
tions  much  like  present  day  operating  systems.  It  would 
seem  to  be  feasible  to  use  the  same  guidelines  for  trans¬ 
portability  as  have  been  used  for  PLANIT  and  PQS  since 
most  operating  systems  are  written  in  higher  level  lan¬ 
guages.  To  be  sure,  it  would  have  to  incorporate  far 
more  generality  than  the  present  MAGIC  system. 

If  such  an  effort  should  be  undertaken,  and  prove 
to  be  successful,  then  both  PLANIT  and  PQS  could  be 
modified  to  run  under  that  system  rather  than  the  present 
MAGIC  s’  stem.  Then  it  would  become  profitable  to  work 
out  intercommunication  channels  between  subprograms. 

This  option  would  seem  to  have  the  greatest  payoff 
in  the  long  run,  especially  because  of  the  advantages 
offered  by  a  transportable  operating  system.  Operating 
systems  now  constitute  environmental  differences  among 
machines  second  only  to  the  hardware  differences.  The 
ability  to  use  the  same  operating  system  on  different 
hardware  would  greatly  reduce  the  entire  transport 
problem.  There  are  many  informed  people  who  would  give 
this  prospect  very  little  chance  for  success,  but  so 
also  they  did  for  PLANIT. 


Is  PLANIT  To  Control  More  Than  One  User?  The  above 
discussion  suggested  that  a  stand-alone  MAGIC  system 
be  developed  which  would  supervise  the  various  programs 
beneath  it,  and  thus  play  a  dispatcher  role  for  any 
interprogram  communication.  If  that  option  was  adopted, 
this  pi’oseni  question  would  be  irrelevant. 

Having  PLANIT  in  control  of  more  than  one  user 
is  a  matter  of  importance  only  if  PLANIT,  being  run  in 
one  of  the  presently  conventional  ways,  attempts  to 
communicate  with  some  other  program  on  the  same  computer 
which  is  not  related  to  PLANIT  or  its  operating  system. 


Thus,  this  is  a  question  of  not  t  ing  interprogram  com- 
mui  ication  with  PLAN IT  going  today,  without  extensive 
developmental  work. 

The  thrust  of  the  question  is  whether  PLAN IT 
execution  can  be  suspended  while  communication  has 
shifted  to  the  other  program.  If  PLANIT  is  running 
in  the  one-copy-per-user  mode,  as  it  usually  is  under 
a  host  time-sharing  system,  then  execution  can  be 
suspended  while  the  user  is  interacting  with  t ho  other 
program,  and  resumed  when  control  Is  shifted  back  to 
PLANIT  again. 

However,  if  PLANIT  is  running  more  than  one  user, 
PLANIT  itself  cannot  suspend  execution  since  it  must 
continue  to  ,  ovide  service  to  its  other  users.  Thus, 
the  one  user  who,  by  reason  of  interprogram  communication, 
shifts  interaction  to  the  other  program,  must  be  treated 
as  a  special  case  in  PLANIT.  It  will  be  as  though  the 
lesson  scenario  was  interrupted  for  any  reason  (e.g. 
quitting  for  the  day),  except  that  execution  should 
resume  automatically  upon  the  return  to  PLANIT.  This 
will  require  some  new  capabilities  to  be  added  to 
PLANIT,  including  new  author  directives  to  initiate 
the  program  switch,  and  probably  some  new  MIOP  interface 
algorithms  accomplish  the  desired  action. 

If  these  changes  are  made  to  PLANIT,  then  they  could 
be  used  without  regard  to  the  number  of  terminals  PLANIT 
is  currently  running.  Given  sufficient  planning,  the 
same  directives  could  be  used  to  initiate  int erprogram 
communication  if  both  programs  were  running  under  the 
MAGIC  operating  system  as  well,  having  the  advantage 
that  lessons  would  work  without  change  in  either 
environment.  With  this  option,  the  burden  would  bo  on 
the  PLANIT  installer  to  determine  how  to  shift  communi¬ 
cation  over  to  the  different  program ,  temporarily  re¬ 
assigning  the  terminal,  loading  and  executing  the  program, 
and  all  else  that  would  be  entailed.  The  changes  to 
PLANIT  to  permit  this,  although  somewhat  difficult  to 
design,  should  not  be  extensive. 


Can  Program  X  Be  Modified  To  Suit  Specific  Needs  Fox* 
Communication  With  PLANIT?  Put  another  way,  is  Program  X 
expecting  the  intercommunication  with  PLANIT,  or  can  it 
be  made  to?  This  question  relates  to  the  nature  of  the 
other  program  and  how  much  freedom  exists  to  modify  it 
for  best  intercommunication  results  with  PLANIT.  In  the 
case  of  PQS ,  one  would  assume  that  any  accomodations 
deemed  necessary  could  be  built  in  since  both  have 


a  common  developer  and  share  many  other  similarities 
as  well. 

Some  accomodation  may  also  bo  possible  with 
other  software  which  has  had  no  prior  association  with 
PLANIT,  if  the  developer  is  available  and  the  authori¬ 
zation  is  granted.  In  these  cases  it  would  not  only  be 
possible  to  switch  the  user  to  the  other  system  at 
convenient  places  in  the  scenario,  but  it  would  also 
be  possible  to  send  some  data  along  which  would  help 
make  the  interaction  in  the  other  program  more  pertinent, 
or  in  the  case  of  a  return  to  PLANIT,  report  back  some 
indication  of  performance. 

There  will  also  be  cases,  perhaps  the  majority  of 
them,  whoro  no  accomodation  can  bo  made  in  the  other 
program  with  which  PLANIT  desires  to  communicate. 

Two  possibilities  still  remain  for  such  situations: 

•  When  switching  to  the  other  program,  mark 
the  place  so  that  execution  will  return  to 
PLANIT  after  the  other  program  runs  to 
completion. 

•  Write  an  add-on  front-end  processor  for  the 
other  program  which  examines  the  input  and 
output  messages  on  the  way  to  the  computer 
(or  user),  and  initiates  appropriate  switch 
action  based  on  the  content  of  the  messages. 

Either  option  can  allow  the  other  program  to  run 
unmodified.  However,  without  the  front-end  processor, 
n  user  who  has  been  switched  to  the  other  program  will 
be  ovitside  of  any  possible  supervisory  control  needed 
for  training. 

The  front-end  processor  will  probably  bo  moro 
costly  and  difficult  to  develop  than  building  the 
accomodation  into  the  other  program.  However  some  cases 
simply  do  not  provide  the  choice. 

Probably  any  attempt  to  make  PLANIT  communicate 
with  another  progiuun  will  involv  some  design  and 
modification  work,  almost  certainly  to  PLANIT,  and 
most  likely  to  the  other  program  ns  well.  The  addition 
to  PLANIT  should  be  n  one-time  effort  which  ought  to 
handle  a  variety  of  situations.  The  modification  to 
the  other  program  will  need  to  bo  specific  to  the 
requirements  of  PLANIT. 


Assuring  Portability 


One  of  the  most  difficult  aspects  of  portable 
programming  is  the  discipline  required  to  adhere 
to  the  programming  conventions.  This  might  at 
first  look  like  an  obvious  kind  of  statement  but  the 
problem  arises  because  the  finished  program  might 
execute  properly  and  still  not  be  right.  The  error 
will  not  show  up  until  it  Is  Installed  on  a  different 
computer. 

Some  portability  conventions  are  enforced  by 
the  software  which  is  used  to  aid  program  development 
and  installation.  However,  it  is  not  possible  to 
protect  aga .  st  all  possible  errors  of  this  kind. 

There  are  several  examples  of  this  kind  but  the  most 
common  is  mistaking  a  given  design  value  in  the  local 
computer  as  a  constant  across  all  computers.  Thus, 
one  might  make  this  mistake  by  assuming  that  entries 
in  a  particular  dictionary  are  always  composed  of  a 
constant  number  of  words  when  in  fact  the  number 
might  vary  depending  upon  how  many  words  are  used 
to  hold  a  user-supplied  name.  This  could  vary  from 
two  characters  per  word  to  ten,  depending  on  the 
computer. 

Various  ideas  have  been  explored  to  detect  such 
errors  during  program  generation  but  these  numbers 
are  so  interrelated  with  the  program  logic  that  no 
automatic  syntax  check  has  been  found  for  them. 

There  is  another  procedure  which  does  appear  to 
hold  promise.  To  be  sure,  such  errors  will  be  found 
as  soon  as  the  move  is  made  to  another  machine.  If 
tho  originating  computer  is  sufficiently  large,  it 
might  be  made  to  simulate  another  computer  for  purposes 
of  checking  tho  conversion  logic  of  the  newly  developed 
program.  The  simulation  would  not  be  nearly  as 
comprehensive  as  it  might  first  appear. 

Most  of  the  errors  will  bo  made  through  faulty 
references  to  data  where  the  references  were  not 
properly  adjusted  for  differences  among  machines. 

So  long  as  the  originating  computer  exceeds  by  at  least 
one  by to  the  minimum  number  of  bytes  per  word,  n  second 
MIOP  interface  program  could  be  written  which  assumes 
the  same  machine  but  with  smaller  word  size,  effectively 
discarding  the  extra  byte  space  in  each  computer  word. 
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Then,  after  a  new  program  had  been  completely  checked  out 
on  the  primary  MIOP  installation  interface  and  determined 
to  be  free  from  errors,  it  could  be  run  again  under  the 
second  MIOP  interface  which  would  provide  many  of  the 
conditions  to  be  encountered  during  transport.  Such  a 
test  would  significantly  increase  the  confidence  in  the 
transportability  of  the  finished  product. 


DATA  BASE  CONVERSION  PROGRAM 


PLANIT  automatically  keeps  a  detailed  data  record 
on  all  trainees  who  are  receiving  instruction.  This 
data  record  is  active  during  the  course  of  the  training, 
providing  historical  information  so  that  the  lesson 
scenario  can  be  continually  adapted  to  meet  a  particular 
individual's  training  requirement.  Following  the 
instructional  session,  the  record  is  also  available  to 
the  lesson  author  for  inspection.  However,  as  is  true 
for  so  many  computer-kept  data  bases,  the  mass  of  data 
is  normally  so  great  as  to  discourage  most  authors 
from  using  them  beneficially. 

The  Portable  Query  System  is  designed  for  problems 
of  extracting  relevant  information  from  large  data  bases. 
Using  the  PQS,  one  can  specify  in  the  query  statement 
what  kinds  of  data  are  to  be  reported  for  particular 
needs . 


The  Data  Base  Conversion  Program  (CONVERT)  trans¬ 
lates  PLANIT' s  student  record  data  bases  into  the 
format  acceptable  to  PQS,  complete  with  all  necessary 
Attribute  name  definitions  and  control  cards. 

The  input  for  CONVERT  consists  of  a  set  of  student 
records,  all  belonging  to  one  lesson,  taken  from  PLANIT’ s 
UNLOAD-to-tape  format.  This  particular  format  was  chosen 
for  three  reasons: 

•  A  magnetic  tape  provides  a  tangible  medium  for 
an  input  file. 

•  This  particular  format  in  PLANIT  is  the  only 
one  that  collects  all  relevant  records  together 
in  one  file. 

•  The  production  of  the  UNLOAD  tape  will  be 
routinely  done  in  many  instructional  environments. 

The  UNLOAD  tape  containing  all  the  student  records 
for  a  given  lesson  comprises  a  comprehensible  collection 
of  data.  However,  the  user  of  the  CONVERT  program  is 
not  restricted  to  that  one  data  base  input  format.  The 
job  may  be  run  repeatedly,  if  desired,  producing  a 
different  data  base  for  each  UNIX3AD  tape  that  is  submit¬ 
ted.  Then,  by  removing  the  final  (terminator)  card  from 
each  output  data  base  deck,  the  decks  can  simply  be 
stacked  together  to  form  one  large  data  base.  One  of 
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the  removed  terminator  cords  is  then  put  at  the  end  of 
the  deck  collection,  and  the  result  is  ready  to  bo 
submitted  to  the  PQS  system  as  one  large  data  base. 

Thus  loaded,  the  user  is  ready  to  formulate  questions 
of  the  most  general  sort  such  as: 

•  What  a  particular  student  did  in  a  particular 
lesson 

•  What  many  (or  all)  students  did  in  a  particular 
lesson 

•  What  a  particular  student  did  in  all  the 
lessons 

•  What  all  the  students  did  in  all  the  lessons 

Many  different  kinds  of  information  will  be  avail¬ 
able  from  the  student  record  data  base,  including 
specifics  about  any  answer  the  trainee  gave  during  the 
courso  of  instruction,  to  very  general  kinds  of  infor¬ 
mation,  such  as  the  difficulty  level  of  various  questions 
in  the  scenario.  The  information  can  bo  useful  both 
\o  assess  the  performance  of  the  students  and  to  assess 
the  quality  of  the  lessons. 

A  complete  Users'  Manual  for  the  CONVERT  program 
is  included  in  Appendix  C.  It  contains  instructions  for 
using  the  CONVERT  program  and  examples  of  the  kinds  of 
information  that  can  be  retrieved  as  a  result. 

The  CONVERT  program  is  transportable,  in  the  same 
way  as  are  both  PLANIT  and  PQS  except  that  no  locally- 
written  MIOP  program  is  required.  Instead,  the  user 
will  review  a  FORTRAN  READ  and  WRITE  statement  and 
modify  them  if  necessary  to  the  conventions  of  the 
computer  on  which  the  program  is  to  be  run.  Also, 

CONVERT  is  a  batch  program  rather  than  interactive. 
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THE  MIOP  INTERFACE  TEST  PROGRAM 


Part  of  the  installation  procedure  for  PLANIT  is 
to  write  three  subroutines  called  LDBYTE,  SBYTE  and 
MIOP.  The  first  two  are  very  simple  character  moving 
routines,  normally  taking  only  a  few  minutes  to  code. 

The  third,  MIOP,  moves  data  between  the  PLANIT  program 
and  the  peripheral  devices. 

The  PLANIT  program  code  is  adapted  to  the  archi¬ 
tecture  of  the  target  computer  through  a  generation 
step  in  which  the  characteristics  of  the  target 
machine  ar  i  (.presented  in  generation  parameters.  This 
part  was  described  earlier.  However,  PLANIT  communicates 
with  the  peripheral  devices  on  the  target  computer  via 
an  interface  to  a  subroutine,  MIOP.  The  interface  for 
this  subroutine  is  defined  but  the  code  which  implements 
the  peripheral  communication  must  be  written  as  a  part 
of  the  installation  effort. 

When  the  MAGIC  operating  system  was  extracted  from 
PLANIT,  the  same  interface  was  kept.  Thus,  the  same 
MIOP  program  must  be  written  to  interface  the  MAGIC 
system  to  the  target  computer  as  if  PLANIT  was  being 
installed. 

The  interface  is  relatively  simple.  It  consists 
of  an  array  of  thirteen  integer  numbers,  where  different 
number  positions  contain  codes  for  different  peripheral 
operations.  These  codes  convey  such  information  as: 

•  What  operation  is  to  be  performed  (e.g.  Open, 

Read,  Write,  Close,  etc.) 

•  Which  peripheral  device  is  intended  (e.g.  Disk, 
Tape,  Card  Reader,  Card  Punch,  Line  Printer,  etc.) 

•  Where  to  find  (or  put)  the  data  in  core 

•  How  much  data  should  be  moved 

•  Location  of  the  data  on  the  peripheral  device 
(if  appropriate) 

•  Where  to  report  back  a  status  number  that  will 
indicate  the  success  or  failure  of  the  operation 


Tho  MIOP  interface  is  so  well-defined  that  the 
coder  does  not  need  to  know  a  thing  about  the  operation 
of  the  computer  system  that  uses  it.  It  could  easily 
be  coded  before  PLANIT  or  PQS  arrives.  Examples  of 
tho  coding  of  MIOP  are  available  but  the  final  code 
must  bo  prepared  at  the  target  site  by  a  system  pro¬ 
grammer  who  knows  the  conventions  of  communicating 
with  the  local  peripheral  devices. 

Since  the  MIOP  interface  handles  many  functions 
(virtually  all  of  the  communication  with  peripheral 
devices),  some  of  its  operations  will  be  exercised 
frequently  and  some  inf requently .  For  example,  if 
PLANIT  was  being  installed  on  a  target  computer,  some 
of  the  MIOP  communication  options  might  not  get  exer¬ 
cised  for  a  week  or  more  after  the  system  has  been 
made  operational.  It  would  require  more  sophistication 
than  would  normally  be  expected  to  run  through  exercises 
in  PLANT']’  which  would  test  every  MIOP  function. 

I t  is  for  this  purpose  that  the  MIOP  Interface 
Test  Program  was  developed.  The  Test  Program  uses 
ihc  same  MAGIC  operating  system  that  is  used  by  both 
PLANIT  and  PQS,  thus  it  works  with  the  same  MIOP 
interface  and  requires  the  same  MIOP. 

The  Test  Program  is  interactive.  It  contains  a 
fixed,  built-in  scenario  which  is  designed  to  system¬ 
atically  test  each  and  every  MIOP  function  that  can 
be  set  up  in  the  interface.  It  not  only  tests  tho 
operations,  but  also  attempts  to  move  data,  both  to 
and  from  the  peripherals.  It  checks  the  data  to  make 
sure  it  was  moved  properly. 

As  the  scenario  progresses,  the  user  receives 
comments  regarding  the  particular  operation  being  tested. 
If  the  test  is  successful,  the  user  is  so  informed.  If 
not,  some  suggestions  are  made  concerning  the  probable 
cause  of  the  error  (from  examining  the  internal  data), 
and  a  general  description  of  the  repairs  that  need  to 
be  made  is  also  given. 

Since  some  interface  requirements  might  not  be 
implemented  in  the  first  versions  of  the  local  MIOP 
(such  as  tape  operations  and  enfoi’ced  time  limits  on 
terminal  reads),  the  Test  Program  asks  the  user  at 
several  points  if  the  next  feature  has  been  implemented 
before  proceeding  with  the  test.  Therefore,  the  coder 
of  tho  MIOP  subroutine  can  check  out  subsections  of  it, 
i f  desired. 


It  is  also  possible  that  tho  Tost  Program  may  be 
used  several  times  before  the  MIOP  subroutine  is 
pronounced  "clean.”  On  the  assumption  that  some 
users  will  stop  the  test  when  an  error  is  found,  the 
Test  Program  provides  opportunity  at  the  beginning 
to  re-enter  the  tost  sequence  at  any  point  the  user 
chooses.  The  user  may  also  choose  to  terminate  the 
test  by  typing  the  word,  "STOP"  on  the  terminal. 

In  addition  to  the  dialog  that  takes  place  during 
the  test  interaction,  a  summary  is  printed  anytime  the 
program  is  stopped  or  reaches  its  end.  The  summary  is 
called  a  "Box  Score"  in  which  are  listed  each  of  the 
tests  that  were  made  during  that  session,  and  the 
result  In  one  word,  "Okay"  or  "Problem."  This  serves 
as  a  reminder  to  the  user  of  the  things  that  still 
are  in  need  of  work. 


Using  The  MIOP  Interface  Test  Program 


The  MIOP  Interface  Test  Program  was  developed  in 
conjunction  with  a  MIOP  subroutine  that  was  known  to 
be  good.  Therefore,  all  tests  should  pass  when  the 
Test  Program  itself  was  working  correctly. 

After  this  stage  was  reached,  it  was  possible  to 
program  some  failures  into  the  MIOP  subroutine  to 
insure  that  the  Test  Program  would  detect  the  failures. 

When  the  Test  Program  appeared  to  be  finished  and 
working  properly,  a  completely  new  and  different  MIOP 
subroutine  was  written.  This  MIOP  had  nothing  in  common 
with  the  good  MIOP  that  was  used  during  development. 

The  MIOP  Test  Program  detected  several  errors  in 
the  new  MIOP  during  the  course  of  several  checks.  Each 
time,  the  error  that  was  detected  was  in  fact  the  fault 
of  the  new  MIOP  and  was  found  in  the  place  pointed  out 
by  the  Test  Program.  When  finally  the  Test  Program 
produced  a  "clean"  Box  Score  for  the  new  MIOP,  it  should 
have  been  finished  and  reliable.  It  was.  No  more  work 
was  required  on  that  MIOP  after  it  passed  inspection  by 
the  Test  Program. 

The  use  of  the  Test  Program  was  an  obvious  savings 
in  this  one  experience  of  writing  the  MIOP  subroutine. 
Errors  were  pointed  out  and  the  nature  of  the  problem 
was  described.  That  makes  the  debugging  task  much 
easier.  Also,  if  the  Test  Program  can  reliably  declare 


a  MIOP  subroutine  to  be  fre?  from  errors,  this  will 
save  a  great  many  "call  backs"  resulting  from  failures 
encountered  at  a  later  time.  There  shouldn't  be  any. 

The  MIOP  Interface  Test  Program  generates  and 
installs  exactly  like  PLANIT  and  PQS.  The  main  difference 
is  that,  whereas  PLANIT  and  PQS  assume  a  working  MIOP 
subroutine,  the  Test  Program  does  not.  If  PLANIT  or 
PQS  does  encounter  an  error  when  MIOP  is  called,  the 
entire  system  is  likely  to  fail  in  very  unpredictable 
ways.  The  Test  Program,  on  the  other  hand,  usually 
continues  to  run  in  spite  of  a  MIOP  failure  and  then 
surveys  the  current  status  of  the  data  to  see  what 
went  wrong.  This  of  course  would  not  be  true  if 
computer  execution  aborted  within  MIOP  itself. 

In  the  few  months  that  the  Test  Program  has 
been  working  and  available,  it  is  a  little  discouraging 
that  more  installers  have  not  gone  to  the  extra  trouble 
of  ins  tiling  and  using  it.  They  probably  need  to  be 
shown  how  effective  it  is  and  how  similar  to  PLANIT  the 
installation  is.  Doing  one  establishes  the  procedure 
for  doing  the  other. 

While  the  Test  Program  apparently  is  very  effec¬ 
tive  at  f.ading  MIOP  problems,  it  cannot  detect  most 
kinds  of  inefficiency.  It  is  quite  difficult  to  make 
most  tests  of  this  sort  because  they  depend  on  the  computer 
environment  under  which  the  program  executes.  There  is 
an  attempt  to  show  the  transmission  speed  to  and  from 
terminals.  Time  functions  are  also  checked  and  a  check 
is  also  made  to  see  if  time  is  really  being  released  for 
other  functions  when  the  Test  Program  is  supposed  to  be 
idle  (e.g.  waiting  for  a  terminal  input). 

If  new  operations  are  added  to  the  standard  MIOP 
package,  it  would  not  be  too  difficult  to  add  tests 
in  the  Test  Program  for  them.  In  that  way  the  Tost 
Program  can  stay  current  with  the  MIOP  requirements 
for  the  code  on  any  given  magnetic  tape  which  is  shipped 
to  a  target  site. 

For  more  information  on  the  MIOP  Interface  Test 
Pi'ogram,  including  a  description  of  each  test  that  is 
made,  the  reader  should  consult  the  User's  Manual  in 
Appendix  D. 


CONCLUSIONS 


It  is  likely  that  somewhere  along  the  way,  a  software 
application  will  be  presented  for  which  the  transportable 
method  of  coding  will  be  totally  inappropriate.  However, 
for  the  assignments  to  date,  the  method  has  worked  w'ell. 

The  most  experience  has  been  with  PLANIT.  So  far, 
PLANIT  has  installed  on  every  appropriate  computer 
attempted.  A  few  have  not  been  satisfied  with  their 
installations  due  to  slow  response  times  but  these  are 
traceable  to  slow  routines  they  were  using,  verified 
by  the  fact  N- it  it  ran  acceptably  fast  on  the  same 
kinds  of  computers  elsewhere. 

In  one  case,  an  installation  attempt,  the  first 
of  its  kind  on  a  computer  of  that  type,  was  dropped 
after  six  months  of  intermittent  work.  Later,  an 
installation  was  successfully  completed  on  an  identical 
computer  in  one  week.  A  lot  depends  on  the  competence 
of  the  installer. 

On  only  one  computer,  the  Burroughs  5500,  was  the 
Installation  finally  declared  unusable.  Although  it 
installed  properly,  the  virtual  paging  hardware  made  it 
impossible  to  keep  critical  code  in  core  to  achieve 
reasonable  response  times.  Newer  virtual  paging 
machines  have  corrected  this  problem. 

The  projects  comprising  this  effort  accomplished 
at  least  three  things: 

•  Built  confidence  in  the  validity  of  the 
transportability  concepts  and  procedures 
by  demonstrating  its  applicability  to  a 
broader  class  of  computers  than  before 

•  Provided  additional  information  about  the 
kinds  of  software  applications  which  could 
feasibly  profit  from  transportable  coding 
methods 

•  Added  new  and  needed  tools  to  promote 
further  investigations  of  transportable 
coding 


RECOMMENDATIONS 


Recommendations  were  made  in  the  discussions  of 
each  of  the  topics  as  they  were  presented.  Therefore, 
their  appearance  again  here  constitutes  a  collected 
summary  of  the  various  recommendations  that  have 
already  appeared. 

It  is  recommended  that: 

•  The  minimum  target  installation  word  size 
for  a  PLANIT  installation  be  reduced  from 
the  present  24  bits  to  16  bits,  providing 
an  extension  of  the  appropriate  PLANIT 
sites  to  those  who  run  mini-computers. 

•  A  thorough  examination  be  made  of  the  system 
library  procedures  being  used  in  the  PDP  11 
installation  of  PLANIT  for  the  purpose  of 
eliminating  the  unneeded  ones  and  realloca¬ 
ting  the  released  core  space  to  more  productive 
PLANIT  work. 

•  A  feasibility  effort  be  initiated  to  determine 
whether  a  transportable  computer  operating 
system  can  be  developed  that  is  patterned  after 

t  the  MAGIC  operating  system  but  has  the  indepen¬ 

dence  from  subordinate  programs  which  the 
MAGIC  system  now  lacks. 

•  A  set  of  author  directives  be  designed  for  and 
implemented  into  PLANIT  which  would  provide 
authoring  capability  for  intercommunication 
between  PLANIT  and  another  (non-PLANTT)  program. 

•  An  installation  procedure  be  designed  which 
would  suspend  a  particular  student’s  work  in 
PLANIT  while  interacting  with  another  program, 
and  permit  resumption  of  PLANIT  interaction 
again  when  the  other  program  returned  control. 
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LANGUAGE  SPECIFICATIONS  FOR  THE 
MACHINE  TRANSPORTABLE  ON-LINE  QUERY  DEMONSTRATION 

INTRODUCTION 

United  States  Army  Research  Institute  (ARI)  contract 
number  DAHC19-76-C-0022  entitled,  "Research  in  Adaptable 
Programming  To  Achieve  Computer  Independence,"  is  oi'ganized 
into  three  demonstration  tasks,  the  third  of  which  is  to 
demonstrate  a  portion  of  an  on-line  query  system  which  has 
the  machine  transportable  qualities  of  a  computer  system 
called  PLANIT.  The  languago  details  and  the  scope  of  the 
effort  of  this  third  demonstration  was  left  to  be  negotiated 
but  it  was  generally  understood  to  encompass  something 
analagous  to  the  on-line  query  portion  of  the  G1M  II  data 
management  system.  Tho  purpose  of  this  document  is  to 
propose  language  specifications  to  meet  this  requirement. 


GUIDELINES 

Several  general  guidelines  were  established  in  a 
meeting  between  tho  contractor  and  Dr.  Larry  Potash  of 
ARI  on  April  1,  1976  for  this  third  demonstration  effort 
and  several  more  specific  guidelines  have  evolved  as  a 


logical  consequence. 


General  Guidelines. 


1.  Tho  demonstration  will  meet  all  the  contract 
requirements,  pertaining  primarily  to  trans¬ 
portability  . 

2.  The  on-line  query  portion  of  a  data  management 
system  will  bo  demonstrated,  using  the  syntax 
of  the  GIM  II  system  as  nearly  as  practical. 

3.  Constraints  must  be  placed  on  the  size  of  the 
language  subset  chosen  in  order  to  keep  the 
scope  of  the  effort  within  the  bounds  of  the 
contract  time  and  money  limits. 

4.  The  data  base  upon  which  the  on-line  query 
operations  will  be  made  will  consist  of  alpha¬ 
numeric  character  records,  like  card  images  but 
not  necessarily  80  characters  long. 

5.  There  will  be  some  components  that  cannot  be 
added  to  the  demonstration  in  tho  present  time 
frame  which  nevertheless  will  have  such  obvious 
importance  to  a  fully  operational  system  that 
the  technical  feasibility  of  adding  them  in  the 
future  must  bo  considered  and  reported. 

6.  There  will  be  several  more  areas,  particularly 
data  base  creation,  modification  and  update, 

which  will  even  bo  beyond  the  scope  for  consideration 
in  the  present  effort. 

Specific  Guidelines: 

1.  The  GIM  II  POR-WITH-WHERK-LIST  format  will  be 

the  general  model  for  the  demonstration.  Specific 
syntax  specifications  will  be  given  below. 

2.  Data  base  creation  and  description  commands  will 
be  included  for  the  purpose  of  supplying  a  data 
base  for  the  demonstration.  The  syntax  and/or 
user  convenience  considerations  will  not  be 
relevant  for  these  commands  since  their  utility 
will  be  solely  for  the  demonstration. 

3.  The  system  will  permit  tho  building  of  a  user 
library  of  query  components.  However,  the 
directives  for  creating,  maintaining  and/or 
protecting  these  dictionaries  will  lack  the 
features  needed  for  a  finished  system.  The 
present  objective  is  solely  to  havo  such  a 


dictionary  available  so  that  its  entries  can  bo 
used  in  on-line  queries. 

4.  System  protection  for  login,  data  base  access, 
etc.,  will  appear  in  the  demonstration  system 
but  only  in  dummy  form.  No  actual  file  or 
password  protection  will  be  needed  for  demonstration 
purposes . 

5.  Multiple  (linked)  data  base  queries  will  not  be 
implemented  in  the  demonstration  system.  While 
several  data  bases  may  be  active,  any  given 
query  will  only  search  one  of  them. 

6.  No  hoiorarchical  relationships  will  exist  between 
data  lists,  hence  also  rio  inversion  operation. 

7.  Data  base  entries  will  occur  within  fixed  fields 
(as  specified  in  the  data  base  description  library), 
and  will  be  one  of  two  types:  alphanumeric  or 
numeric.  Logical  entries  will  be  simulated  so 

that  proper  results  are  obtainod  in  the  demonstration. 

8.  In  addition  to  the  language  features  which  will 
be  Included  for  the  basic  demonstration,  a  list 
of  desirable  options  will  also  be  articulated 
which,  in  the  order  of  their  appearance,  will  be 
added  to  the  basic  demonstration  system  as  time 
and  money  permit. 


PURPOSE 

The  purpose  of  this  demonstration  effort,  as  now 
defined  in  this  document,  is  to  build  a  machine  trnnsportable 
on-line  query  system  which  resembles  insofnr  as  is  practical 
the  operation  of  the  on-line  query  subset  of  the  C.IM  II 
system.  Queries  made  in  this  system  should  yield  print¬ 
outs  similar  to  like  queries  mnde  in  the  CIM  II  system. 

Where  differences  exist,  they  will  be  due  to  unavoidable 
differences  in  hardware  (eg.  printing  dovicos)  or  lack 
of  sophistication  in  the  demonstration  system  compared  to 
the  GIM  II  system,  or  both. 


It  is  recognized  that  the  GIM  II  system  is  a  large 
and  comprehensive  data  management  system  which  has  taken 
many  man-years  to  develop,  which  cannot  possibly  be  fully 
implemented  in  the  few  short  months  of  this  project. 
However,  the  purpose  of  this  project  is  not  to  duplicate 
the  GIM  II  system  or  any  other  like  system.  Rather,  it 
is  to  show  that  on-line  query  functions  are  possible  in 
a  machine  transportable  language,  and  the  GIM  II  query 
format  is  par  icularly  useful  as  a  model  for  such  a 
demonstration.  Therefore,  some  deviations  from  the  GIM  II 
language  format  will  be  expected. 

TOTAL  SYSTEM 

Although  the  remainder  of  this  document  will  pertain 
to  the  specifications  of  a  query  language,  it  is  also  to 
be  understood  that  the  software  which  implements  this 
language  will  be  a  full  time-sharing  system  with  all  the 
usually  expected  system  support  features,  including: 

.  The  support  of  multiple  on-line  terminals 
.  Disk  memory  management 
.  User  accounting 
.  Error  recovery 

It  is  also  understood  that  an  installation  process  will  be 
involved  before  it  can  be  operated  on  a  given  computer. 

The  installation  process  is  well-known,  being  very  similar 
to  that  for  PLANIT,  and  in  fact  should  be  able  to  use  a 
PLANIT  installation  interface  if  one  exists. 


DEMONSTRATION  QUERY  LANGUAGE 


A  5 


The  general  form  for  the  demonstration  query  language 
will  closely  resemble  the  GIM  II  query  specifications  as 
follows: 

(FOR  clause  (Selection  clause))  Verb  clause  (Limiter  clause)# 
In  the  above,  "FOR"  is  a  language  particle  which  serves 
as  a  qualifier  for  the  statement,  and  the  remainder  of  the 
line  will  be  explained  below.  First,  the  various  particles 
of  which  the  line  is  composed  will  be  presented  in  appro¬ 
priate  categories. 

Particles . 


Prepositional  Qualifiers: 
Adjective  Qualifiers: 


FOR,  WITH,  WHERE,  WHEN 

FIRST,  LAST,  GREATEST,  SMALLEST, 
PRESENT,  NULL,  NEAREST 


Connectives:  AND,  OR,  NOT 

Relationals:  GT  (GREATER  THAN) 

GE  (GREATER  THAN  OR  EQUAL  TO) 
EQ  (EQUAL  TO) 

LE  (LESS  THAN  OR  EQUAL  TO) 

LT  (LESS  THAN) 

NE  (NOT  EQUAL  TO) 


Verbs:  LIST,  LIST- VERTICAL  (&  LISTV) , 

COUNT,  TOTAL,  AVERAGE 

Adverb  Qualifiers:  ASCENDING,  DESCENDING 

Nouns:  A  name  beginning  with  a  letter 

and  including  only  letters, 
digits  and/or  hyphens. 


Values : 


Any  characters  enclosed  in 
quotes . 


Symbols:  letters  (A  -  Z) 

digits  (0  -  9) 

—  hyphen  in  name,  minus  sign 
(  —  open  parenthesis 

)  —  close  parenthesis 

.  —  decimal  point 

"  —  quotation  mark 

#  —  line  terminator 

Query  Statement  Format.  Repeating,  the  general  form  for 
the  query  statement  is: 

(FOR  clause  (Selection  clause))  Verb  clause  (Limiter  clause)# 

The  parentheses  in  the  above  general  form  are  there  only  to 
indicate  that  part  of  the  form  which  is  optional  (enclosed 
in  parentheses)  versus  that  part  which  is  mandatory,  that  is, 
the  Verb  clause.  The  above  parentheses  are  not  typed  as  a 
part  of  the  query  statement. 

The  FOR  clause  designates  the  data  base  name  upon  which 
the  Verb  clause  will  operate,  where  the  name  is  of  the  Noun 
form. 

-EXAMPLE- 

POR  EMPLOYEE-LIST  LIST  NAMES  ADDRESSES# 

In  this  case,  "EMPLOYEE-LIST"  is  the  name  of  the  data  base. 

If  the  FOR  clause  is  omitted,  the  most  recently  named  data 
base  will  be  used.  If  none,  an  error  will  be  reported. 

The  Selection  clause  selects  the  data  base  entries  upon 
which  the  verb  clause  will  operate  where  the  clause  will 
begin  with  a  WITH  or  WHERE  particle  and  include  some  relational 
expression. 


-EXAMPLE- 


FOR  EMPLOYEE-LIST  WITH  ANN-SALARY  GE  "15000”  LIST 
NAME  ANN-SALARY# 

The  noun,  ANN-SALARY  describes  one  of  the  entry  catagories 
within  the  EMPLOYEE-LIST  data  base.  WITH  and  WHERE  are 
analogous  particles  with  equivalent  meanings  (although 
their  meanings  could  eventually  become  differentiated  if 
heierarchical  data  list  capabilities  should  be  added  some¬ 
time  in  the  future).  The  relational  phrase,  "ANN-SALARY 
GE  "15000"  determines  which  entries  in  the  data  base  will 
qualify  for  verb  action.  The  entry  to  the  left  of  the 
relational  particle  will  be  a  name  of  an  entry  category 
within  the  named  data  base.  The  entry  to  the  right  of 
the  relational  particle  will  be  similar  to  the  data  in  the 
data  base  under  the  named  category.  The  category  name 
here  is  ANN-SALARY,  and  a  data  sample  is  "15000"  (i.e. 
the  digits,  15000,  enclosed  in  quotes). 

Connectives  can  further  sharpen  selectivity  in  the 
selection  clause. 

-EXAMPLE- 

FOR  EMPLOYEE-LIST  WITH  ANN-SALARY  GE  "15000”  AND 
HIRE-DATE  LE  "1965"  COUNT  NAMES# 

Because  of  the  "AND"  connective,  both  ANN-SALARY  and 

HIRE-DATE  must  qualify  in  order  for  the  name  to  be  counted. 

The  connective  forms  can  be  AND,  OR,  AND  NOT  and  OR  NOT. 

Parentheses  may  enclose  relational  phrases  to  clarify  the 


Intent. 


In  the  following  examples,  a  series  of  three  dots  (...) 


will  designate  some  relational  phrase  such  as  ’ ANN-SALARY 
EQ  ”15000" '  or  ' HIRE-DATE  LE  "1965".' 

-EXAMPLES- 

Verb  clause# 

AND  . . .  Verb  clause# 

AND  WITH  ...  Verb  clause# 

AND  ...  OR  ...  Verb  clause# 
.  OR  .  . .  )  AND  (  .  .  .  OR  .  .  .  ) 


FOR  clause  WITH 
FOR  clause  WITH 
FOR  clause  WITH 
FOR  clause  WITH 


FOR  clause  WITH  ( 
Verb  clause# 


FOR  clause  WITH  ... 
FOR  clause  WITH  (  . . 


AND  NOT  ...  Verb  clause# 

AND  (  ...  OR  ...  ))  Verb  clause# 
Note  in  the  above  that  the  forms,  "WITH  ...  AND  ...  "  and 
"WITH  ...  AND  WITH  ...  "  are  functionally  identical  and  will 
remain  so  unless  heierarchical  data  lists  might  be  added  in 
the  future.  The  allowed  number  of  relational  phrases  and/or 
parenthetical  enclosures  in  one  query  statement  is  limited 
only  by  the  total  amount  of  space  set  aside  to  process  the 
statement . 

One  additional  relational  phrase  contains  an  implied 
"OR"  of  the  form,  "Noun  Relational  Data,  Data,  etc." 

-EXAMPLE- 


FOR  EMPLOYEE-LIST  WITH  HIRE-DATE  EQ  "1971"  "1972"  "1973" 
LIST  NAME# 

The  above  example  is  functionally  identical  to  the  following: 
-EXAMPLE- 

FOR  EMPLOYEE-LIST  WITH  HIRE-DATE  EQ  "1971"  OR  HIRE-DATE 
F,Q  "1972"  OR  HIRE-DATE  EQ  "1973"  LIST  NAME# 


Recall,  also,  that  the  WHERE  particle  can  be  interchanged 
with  the  WITH  particle. 

The  Verb  clause  will  consist  of  the  verb  followed  by 
one  or  more  category  names  that  will  be  acted  on  by  the 
verb  subject  to  the  qualifiers. 

-EXAMPLE- 

POR  EMPLOYEE-LIST  WITH  DIVISION  EQ  "MARKETING” 

LIST  NAME  ADDRESS  TELEPHONE-NUMBER# 

The  named  category  data  from  each  qualifying  data  base 
entry  will  be  listed. 

Verb  operations  will  be  discussed  later. 

The  operation  of  the  Limiter  clause  is  functionally 
identical  to  the  Selection  clause  and  should  be  considered 
to  be  an  extension  of  the  Selection  clause,  providing 
optional  placement  within  the  statement  relative  to  the 
Verb  clause.  Proceeding  the  Verb  clause,  the  Selection 
clause  begins  with  a  "WITH"  or  "WHERE"  particle.  Following, 
it  begins  with  the  "WHEN"  particle,  and  is  called  the 
Limiter  clause.  Either  or  both  kinds  of  clauses  may  appear 
in  a  query  statement.  If  both  appear,  then  an  "AND" 
condition  will  be  implied  between  the  two. 

Verbs.  The  uncomplicated  verbs  are:  COUNT,  TOTAL  and 
AVERAGE.  COUNT  yields  a  numerical  report  of  the  number 
of  data  base  entries  which  qualify  according  to  the 
selection  criteria  in  the  Selection  clause.  TOTAL  yields 
the  numeric  sum  of  qualifying  entries,  requiring  that 
the  entries  be  numeric.  AVERAGE  yields  an  arithmetic 
average  of  qualifying  entries,  also  requiring  the  entries 


to  be  numeric. 

The  various  LIST  verbs  imply  some  sort  of  formatting 
conventions  for  the  report.  Two  varieties  of  reports  are 
envisioned,  columnar  and  vertical.  The  columnar  will  be 
of  the  form: 

-EXAMPLE- 

NAME  ANN-S ALARY 

JOHN  SMITH  16224 

ANN  JONES  18913 

JOE  DOAKES  17323 

etc. 

Column  width  will  be  the  larger  of  the  number  of  data 
columns  in  the  entry  field  or  the  number  of  characters  in 
the  entry  name.  Numeric  data  will  be  adjusted  to  the 
right  margin  of  the  column  while  non-numeric  data  will  be 
adjusted  to  the  left.  Two  spaces  will  separate  the  columns. 

The  vertical  format  will  display  the  data  vertically 
down  the  left  margin  of  the  display  surface. 

-EXAMPLE- 


NAME: 

JOHN  SMITH 

ANN-S ALARY: 

16224 

NAME: 

ANN  JONES 

ANN-SALARY : 

18913 

NAME: 

JOE  DOAKES 

ANN-SALARY: 

17323 

etc. 
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Indentation  will  be  determined  by  the  longest  entry  name. 

The  LIST  verb  will  be  used  to  designate  the  columnar 
display  format  while  the  LIST- VERTICAL  (LISTV)  verb  will 
designate  the  vertical  format.  However,  if  the  LIST  clause 
encompasses  a  collection  of  entry  names  and/or  data  fields 
of  a  magnitude  such  that  the  combined  column  requirements 
of  the  display  exceeds  the  number  of  available  columns  on 
the  display  device,  the  display  will  default  to  the  vertical 
format . 

LIST-ASCENDING  and  LIST-DESCENDING  provide  an  ordered 
listing  of  output  data,  sorted  on  the  basis  of  the  first 
entry  category  name  following  the  verb.  Columnar  format 
is  assumed  unless  the  line  length  is  exceeded  in  which 
case  the  format  will  default  to  vertical. 

Dictionary  Name  String  Substitution.  Any  subset  of  any 
query  statement  may  be  designated  by  a  dictionary  name 
which  has  associated  with  it  a  character  string  to  be 
substituted  for  its  name  in  the  query  statement  so  long  as 
no  partlcal  name  gets  divided.  More  will  be  said  about  this 
feature  later. 

-EXAMPLE- 

POR  EMPLOYEE-LIST  RETIREES  LIST  NAME# 

where  RETIREES  -  AGE  GE  "62" 


i 


REP0RT-N01# 

where  REP0RT-N01  -  a  complete  query  statement. 


Normalizing.  Two  sets  of  normalizing  rules  will  be  applied 
in  the  process  of  executing  a  query  statement.  One  set  of 
rules  will  apply  to  numeric  data  and  the  other  set  to  non¬ 
numeric. 

For  numeric  data  fields  (whether  in  the  query  statement 
or  data  base),  all  blanks  will  be  squeezed  out,  a  decimal 
point  will  be  supplied  at  the  right  if  one  is  missing,  and 
any  leading  and/or  trailing  zeros  will  then  be  eliminated. 
When  two  numeric  values  are  being  compared,  they  will  be 
aligned  by  their  decimal  points  and  the  columns  of  the 
smaller  filled  out  with  zeros  until  the  number  of  columns 
of  the  two  numbers  agree.  A  minus  sign  will  retain  its 
usual  meaning,  appearing  only  to  the  left  of  the  number. 

Any  other  characters  in  the  field  will  cause  an  error  to 
be  reported  for  that  entry  in  the  data  base.  If  the  field 
contains  all  blanks,  the  entry  will  be  considered  to  have 
the  numeric  value  of  zero. 

For  non-numeric  data  fields,  leading  and/or  trailing 
blanks  will  be  eliminated  and  any  embedded  multiple 
contiguous  blanks  will  be  squeezed  to  one  blank. 

Query  statement  selection  criteria  assume  the  comparison 
of  normalized  data.  Normalization  is  only  an  internal 
processing  operation.  No  change  is  made  to  data  within  the 


data  base. 
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Adjective  Qualifiers.  The  Adjective  Qualifiers  are  used 
in  a  variation  of  the  Selection  clause  format.  Instead 
of  the  normal  relational  pattern  (i.e.  ANN-SALARY  GE 
"15000"),  the  relational  particle  and  the  data  item  is 
onitted  and  the  adjective  particle  is  inserted  ahead  of 
the  entry  name  noun. 

-EXAMPLE- 

FOR  EMPLOYEE-LIST  WITH  GREATEST  ANN-SALARY  LIST  NAME# 
This  same  statement  pattern  is  also  used  for  the  adjective 
particles,  FIRST,  LAST,  SMALLEST,  PRESENT  and  NULL.  The 
remaining  adjective  particle,  NEAREST,  stands  in  place  of 
tie  relational  particle  in  the  normal  statement  format. 
-EXAMPLE- 

FOR  EMPLOYEE-LIST  WITH  ANN-SALARY  NEAREST  "15000" 

LIST  NAME# 
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QUERY  LANGUAGE  SYSTEM  SUPPORT  FEATURES 


Although  tho  present  demonstration  is  limited  to  the 
on-line  query  component  of  a  data  management  system,  it 
will  be  necessary  to  include  some  limited  capability  for 
creating  and  cataloguing  a  data  base  and  for  building  the 
necessary  dictionaries  that  will  bo  needed  in  composing 
the  queries.  Certain  points  need  to  be  clearly  articu- 
lated  concerning  tho  difference  in  approach  to  the  on-line 
query  component  from  that  to  the  system  support  features: 

1.  It.  is  expected  that  demonstrations  before  visitors 
will  be  restricted  to  the  formulation  of  on-line 
queries  and  viewing  the  results.  The  system 
support  features  will  be  necessary  for  the  setting 
up  of  the  demonstration  but  will  not  bo  exercised 
during  tho  demonstration. 

2.  The  G I M  II  system  is  being  used  as  a  model  for  the 
on-line  query  component  with  attention  given  to 
human  factors  while  the  system  support  features 
may  be  relatively  rigid  in  format  and  require 
more  operator  orientation. 

3.  The  on-line  query  component  consists  of  a  language 
and  system  operations  which  are  likely  to  survive 
the  present  demonstration  project,  the  conventions 
of  which  might,  with  some  refinement,  be  accepted 
as  a  kind  of  standard.  However,  for  the  system 
support  language  conventions,  no  such  standardization 
is  suggested  since  future  developments  of  this  portion 
of  t  lie  system  may  want  to  significantly  alter  those 
convent  ions . 

Therefore,  the  purpose  of  the  system  support  language 
features  is  solely  to  make  a  data  base  available  to  the 
on-line  query  portion  of  tho  system.  Dictionaries  will 


a  15 


bo  constructed  with  tho  objective  of  making  the  queries 
respond  appropriately,  whereas  a  totally  different  approach 
to  dictionary  building  would  probably  be  taken  if  this  part 
wore  being  Included  in  the  "finished"  system. 

Data  Bases.  A  data  base  will  simply  consist  of  a  collection 
of  cai d  images  located  in  sequential  order  on  the  memory 
unit  'probably  a  magnetic  disk)  which  will  be  searched  in 
rospoi  so  to  on-line  queries.  The  number  of  columns  in  each 
card  image  data  base  record  (entry)  will  be  determined  by 
a  system  generation  parameter.  The  data  base  will  bo 
created  fiom  a  card-reader-like  device  which  shall  accept 
standard  i  omputer  cards  in  the  following  arrangement: 

Card  *1:  DATA-BASK  name# 

Card  #2:  data 
Card  #3:  data 

Card  #m:  data# 

Card  #m+l:  data 

• 

Card  #mfn:  data# 

(etc  ) 

Kina  card:  $$$$ 

In  a  narrative  of  the  above  example,  the  first  card 
of  a  new  lata  base  contains  the  particle,  DATA-BASK, 
followed  >y  a  user-chosen  data  base  name.  That  name 
will  be  cvtaloguod  for  vise  after  the  "KIR"  particle. 
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The  next  card  begins  the  first  entry  in  the  data  base. 
Multiple  cards  may  be  used  to  supply  a  single  entry.  A 
character  on  a  card  will  signal  the  end  of  that  particular 
entry  and  the  remainder  of  that  card  will  be  blank.  The 
result  will  bo  to  create  an  internal  entry  as  long  as  the 
combined  number  of  columns  on  the  card.  If  a  query  statement 
should  refer  to  entries  which  have  been  defined  to  reside 
ip  columns  beyond  the  end  of  the  character,  blank  entities 

will  be  assumed. 

Each  succeeding  data  base  entry  follows  in  clusters  of 
one  or  more  cards. 

The  data  base  creation  is  concluded  when  the  "$$$$" 
card  is  received. 

Error  checking  during  data  base  creation  will  be 
restricted  to  verification  of  a  proper  datn  base  name  and 
the  presence  of  an  all-blank  card  beyond  any  character. 

Name  Attribute  Dictionary  of  Data  Base  Entries.  The  user 
may  define  noun-type  names  which  specify  the  data  types 
for  any  column  field  within  a  data  base.  This  dictionary 
is  associated  only  with  the  data  base  for  which  it  has  been 
built.  The  format  for  defining  such  a  name  is: 

FOR  data-base-name  DECLARE  attribute-name  ~  cl,  c2,  type# 
(where  cl  «  column  1,  c2  "  column  2  and  type  -  C  for 
character  strings  or  type  -  N  for  numbers) 

The  attribute-name  is  a  standard  noun  form  to  be  used  in 
query  statements.  The  section  on  normalization  describes 
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the  manner  In  which  the  named  attribute  fiolds  will  be 
processed  during  response  to  query  statements.  Fields 
may  be  defined  which  overlap  with  other  fields  or  coincide 
with  them  to  permit  added  flexibility  in  response  selectivity 
and  print  formats.  However,  numerical  fields  should  only 
be  defined  to  spnn  numerical  data.  The  column  numbers  in 
the  declaration  statement  are  those  from  the  cards,  accumu¬ 
lated  in  the  case  of  multiple  cards  per  entry. 

i 

-EXAMPLE- 

FOR  EMPLOY EE-L 1ST  DECLARE  NAME  -  1,  25,  C  # 

10R  EMPLOYEE-LIST  DECLARE  ANN-SALARY  -  52,  60,  N  # 

If  the  FOR  clause  is  missing  (i.e.  the  statement 
begins  with  the  DECLARE  particle),  the  last  mentioned 
data  base  name  is  assumed. 

These  attribute  name  declaration  statements,  as  above, 
may  be  supplied  In  the  card  stream  or  at  the  terminal  (or 
aoth) .  I C  in  the  card  stream,  insert  a  card  just  prior 
to  the  end  "$$$$"  card  with  only  a  #  in  column  one.  Then 
any  number  of  declaration  cards  may  be  supplied  between 
the  card  and  tho  "$$$$"  card.  A  command  at  the  terminal: 

READ-CARDS  U 

will  activate  tie  card  reader  and  the  terminal  will  cease 
to  bo  act ive  unt il  the  "$$$$"  end  card  has  been  read. 

Thus,  tho  card  reader  will  simply  bo  regarded  as  an  alternate 


terminal,  accepting  the  same  command  formats. 

Multiple  DECLARE  statements  may  be  given  using  semi¬ 
colons  to  separate  each  attribute  name  as  follows: 

-EXAMPLE- 

FOR  EMPLOYEE-LIST  DECLARE  NAME  -  1,  25,  C  ;  ANN-SALARY 
-  52,  60,  N  # 

The  allowable  length  of  such  an  input  will  be  determined  by 
a  system  generation  parameter  which  governs  the  amount  of 
space  set  aside  to  process  a  terminal  response. 

Dictionary  of  Substitution  String  Names.  When  nouns  are 
found  in  a  query  statement  which  also  occur  in  this  dictionary, 
the  character  string  associated  with  the  dictionary  name  will 
be  substituted  for  the  noun  in  the  query  statement  before 
further  processing  takes  place.  Any  string  may  be  thus 
defined  and  named  in  this  dictionary,  including  strings  that 
contain  the  names  of  other  strings.  Two  such  dictionaries 
will  be  kept,  one  unique  to  the  data  base  being  queried  and 
t he  other  being  general  for  all  data  base  queries.  The 
format  for  defining  the  string  follows: 

FOR  data-base-name  DEFINE  string-name  «  anything  # 

If  the  FOR  clause  is  omitted,  the  string-name  will  be 
entered  in  the  global  dictionary.  Otherwise,  it  will  be 
entered  in  the  dictionary  belonging  to  the  named  data  base. 

-EXAMPLE- 

i 


FOR  EMPLOYEE-LIST  DEFINE  RETIREES  AGE  GE  "62"  # 
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The  string  being  defined  may  be  completely  arbitrary 
except  that  is  may  not  contain  a  character  other  than 

the  one  that  designates  the  end  of  that  line.  Note  that 
the  character  is  not  part  of  the  string  being  defined 
in  the  above  example.  Multi-line  strings  may  be  defined. 

PRINCIPLES  OF  OPERATION 

In  general,  this  demonstration  system  will  accept 
tie  aforementioned  statement  forms  at  the  terminal  or, 
following  a  Rl  AD-CARDS  command,  from  the  card  reader.  If 
from  the  card  reader,  then  activity  at  the  terminal  will 
cease  until  tie  "$$$$"  card  is  received  at  the  card  reader. 
However,  outpi t  will  continue  to  come  to  the  terminal 
printer. 

The  system  will  contain  four  particle  dictionaries, 
with  some  of  the  dictionaries  partitioned  as  needed; 

1.  Dictionary  of  documented  system  particles, 
segmented  according  to  the  kind  of  particle 
(e.g.  nouns,  verbs,  relationals,  etc.) 

2.  Dictionary  of  data  base  names 

3.  Dictionary  of  attribute  names  (one  for  each 
data  base) 

4.  Dictionary  of  substitution  string  names,  segmented 
into  global  and  specific. 

Where  a  particular  kind  of  particle  is  expected  in  the 
syntax  of  the  statement,  the  corresponding  dictionary  will 
be  searched  first  to  determine  the  meaning  of  the  particle 


i  "  v 


name.  If  that  fails,  the  specific  string  substitution 
name  dictionary  will  be  searched  next.  Should  that  fail, 
the  attribute  name  dictionary  will  then  be  searched  but 
only  if  an  attribute  name  fits  the  syntax  at  that  point. 

StiLl  failing,  the  global  string  substitution  name  dictionary 
would  then  be  searched. 

Terminal  Report.  In  addition  to  the  report  implied  in 
the  query  statement,  the  query  statement  itself  will  be 
reproduced  at  the  head  of  the  report.  In  addition,  if 
any  string  substitution  occurred  in  the  query  statement, 
the  fully  expanded  version  of  the  query  will  also  be 
rep roduced. 

At  the  end  of  the  report  will  be  a  status  line  such 

as: 

COUNT:  15  OF  40 

where  the  first  number  refers  to  the  number  of  data  base 
entries  which  were  selected  for  verb  action,  and  the  second 
refers  to  the  total  number  of  entries  searched. 

Halting  The  System.  The  operation  of  the  system  will  be 
brought  to  a  halt  with  the  command: 


HALT  ft 
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ACCEPTABLE  SYSTEM  REPERTOIRE 

This  document  was  produced  with  the  realization  that 
more  is  probably  being  proposed  than  there  will  be  time 
to  complete.  The  purpose  for  doing  this  is  to  avoid  any 
waste  of  remaining  time  while  agreement  is  reached  on 
how  to  use  the  closing  days  of  the  contract  period, 
assuming  the  the  minimum  basic  system  has  been  completed. 

Rather  than  redefine  what  is  being  proposed  as  the 
minimum  basic  system,  the  inverse  approach  will  be  used, 
which  amounts  to  a  prioritized  list  of  what  will  not  be 
included  if  time  runs  out.  In  this  list,  the  items  listed 
first  will  be  the  first  to  be  eliminated  in  a  time  crunch. 

E  ren  ;  f  all  listed  items  are  eliminated,  the  remaining 
system  will  still  support  a  very  impressive  on-line  query 
d  omons t  r  at i on . 

1.  LIST-ASCENDING  and  LIST-DESCENDING 

2.  \ariable  record  lengths  in  data  base  entries, 
requiring  uniform  fixed  length  records. 

3.  Columnar  format  in  printing. 

I.  Global  substitution  string  name  dictionary. 

3 .  Specific  substitution  string  name  dictionary. 

3.  Not  accept  parentheses  in  query  statements. 

7.  Accept  a  maximum  of  one  connective  in  query  statements. 
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Despite  the  number  of  items  listed,  the  present 
goal  only  regards  the  first  two  as  tentative.  The  others 
wil]  be  considered  only  in  the  event  of  unforeseen  problems. 
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PREFACE 


An  attempt  was  made  in  this  document  to  combine 
the  reference  manual  format  with  a  narrative  style. 

It  is  hoped  that,  with  a  great  deal  of  tolerance  on 
the  part  of  the  reader,  this  method  will  make  the 
document  readable  to  the  new  user  as  well  as  useful 
to  the  experienced  one. 

The  section  numbers  used  in  the  document  imply 
the  use  headings  and  subheadings  in  a  modified  outline 
format.  This  organization  seemed  to  lend  itself  a 
little  better  to  the  narrative  style.  If  the  reader 
is  unfamiliar  with  this  numbering  scheme,  a  brief 
explanation  may  clarify  it.  In  place  of  the  common 
outline  form: 

I . 

A. 

1. 

a. 

II. 

A. 

1. 

a. 

the  following  are  used: 

1.0 

1.1 

1.11 

1.111 

2.0 

2.1 

2.11 

2.111 

Therefore,  each  "X.0"  indicates  an  introduction  to  the 
next  main  topic,  and  within  that  section,  each  decimal 
place  indicates  the  next  subpoint  level  (level  of 
indentation).  The  indentation  shown  in  the  Table  of 
Contents  should  help  to  clarify  the  notation. 


B 


TABLE  OF  CONTENTS 

Page 


1.0  INTRODUCTION  1 

2.0  RULES  GOVERNING  CHARACTER  USAGE  1 

2.1  NAMES  2 

2.2  NUMBERS  2 

2.3  DELIMITERS  3 

2.4  STATEMENT  TERMINATOR  3 

2.5  CONTROL  STATEMENT  DESIGNATOR  4 

2.6  BLANKS  4 

2.7  PARENTHESES  5 

3.0  INPUT  FORMS  6 

3.1  QUERY  STATEMENT  FORM  6 

3.11  PARTICLE  NAMES  FOR  THE  QUERY  STATEMENT  FORM  6 

3.12  DATA  PARTICLES  FOR  THE  QUERY  STATEMENT  FORM  7 

3.13  QUERY  STATEMENT  GENERAL  FORMS  8 

3.131  FORM  NUMBER  ONE  EXAMPLES  9 

3.132  FORM  NUMBER  TWO  EXAMPLES  9 

3.2  DATA  BASE  ENTRY  FORM  10 

3.3  CONTROL  STATE  ENTRY  FORM  11 

3.4  INPUT  DEVICE  FORMS,  TERMINAL  VS.  CARDS  11 

4.0  DATA  BASE  CREATION  12 

4.1  DECLARING  A  NEW  DATA  BASE  12 

4.2  ADDING  TO  A  NAMED  DATA  BASE  12 

4.3  ADDING  TO  THE  CURRENT  DATA  BASE  13 

4.4  DAT \  BASE  ORGANIZATION  14 

5.0  THE  QUERY  STATEMENT  17 


5.1 

5.2 


DAT \  BASE  IDENTIFICATION 
THE  SELECTION  CLAUSE 


17 

IS 


m  yi 


B 


Page 

5.21  COMPARISON  OF  SELECTION  CLAUSES  IN  THE  TWO  FORMS  18 

5.22  NATURE  AND  PURPOSE  OF  THE  SELECTION  CLAUSE  19 

5.23  COMPARISON  OF  DATA  20 

5. 24  SIMPLE  SELECTION  CLAUSES  22 

5.25  COMPOUND  SELECTION  CLAUSES  22 

5.26  THE  USE  OF  ADJECTIVES  IN  THE  SELECTION  CLAUSE  25 

5.27  NEGATED  COMPARISONS  IN  THE  SELECTION  CLAUSE  26 

5.28  ABBREVIATED  "OR"  COMPARISONS  26 

5.29  SELECTION  CLAUSE  VARIATIONS  27 

5.3  THE  REPORTING  VERB  28  * 

5.31  LIST  29 

5.32  LIST- VERTICAL  AND  LISTV  30 

5.33  CO UN i  30 

5.34  TOTAL  31 

5.35  AVERAGE  31 

.4  THE  REPORT  CLAUSE  32 

.5  TERMINATOR  CHARACTER  32 

6.0  REPORTING  FORMATS  33 

6.1  NUMERIC  VALUE  REPORTS  33 

6.2  DISPLAYING  DATA  33 

6.21  COLUMNAR  DATA  DISPLAY  34 

6.22  VERTICAL  DATA  DISPLAY  35 

7 . 0  MACROS  36 

7.1  DEFINING  AND  USING  MACROS  36 

8.0  COMMAND  VERBS  39 

8.1  PRESTORING  A  CARD  DECK  39 

8.2  USING  A  PRESTORED  CARD  DECK  40 

8.3  CREATING  OR  EXTENDING  A  DATA  BASE  41 

8.4  DEFINING  A  MACRO  NAME  42  * 

8.5  DECLARING  ATTRIBUTE  NAMES  42 

9.0  CONTROL  STATEMENTS  43- 

9.1  USER  SIGNOFF,  $OUT  43 

9.2  OPERATOR  CONTROLS  43 


10.0 


OPERATING  PROCEDURES 


45 


10.1  SIGNING  ONTO  THE  SYSTEM  45 

10.2  TERMINAL  PROMPTS  45 

10.3  LINE  ECHOING  46 

10.4  ERROR  MESSAGES  46 

10.5  CORRECTING  INPUT  LINE  ERRORS  47 

10.6  MODE  SWITCHING  47 

10.7  SIGNING  OFF  FROM  THE  SYSTEM  48 


APPENDIX  .1:  INSTALLATION  INFORMATION 
APPENDIX  H:  INITIALIZATION  DECK 


PORTABLE  QUERY  SYSTEM  USER'S  MANUAL 


1.0  INTRODUCTION 


The  Portable  Query  System  (PQSl  whs  developed 
under  contract  (No.  11AHC1U-76-C-00J42)  for  the  United 
States  Army  Research  Institute.  The  purpose  of  the 
system  is  to  provide  on-line  retrieval  from  a  uniformly- 
defined  data  base  in  a  way  that  can  be  replicated  on 
a  variety  of  computers.  Data  bases  consist  of  multiple 
chained  n  cords  where  each  record  contains  a  string  of 
an  arbitr.  ry  number  of  keyboard  characters. 

The  Query  system  can  be  moved  to  another  computer 
through  a  well-defined  installation  process  which  is 
virtually  identical  to  the  Installation  of  the  PI.ANIT 

system. 


The  data  bases  for  the  Query  system  require  no 
Installation  when  moved  from  one  computer  to  another. 

Vt  most,  characters  which  differ  on  the  new  machine 
nay  need  translating. 

This  user's  manual  is  valid  for  all  installations 
of  PQS.  Variations  which  may  occur  will  be  noted. 


! .  0  Rill  ES  liOVKHNlNG  I'll  Alt  ACT  KR  US  AUK 


Tht  syntax  of  query  statements  dictate  fairly 
stringent  rules  in  the  use  of  the  characters  which 
make  up  the  statement.  Where  freedom  is  needed  to 
show  the  arbitrary  character  strings  which  may  occur 
in  tat'  data  base,  these  strings  will  be  enclosed 
hotw *en  lelimiting  characters,  either  primes  (')  or 
quot  it  ion  ma  ks  (").  Thus,  when  considering  query 
•  tat  ‘ineni  particles,  the  delimited  string  will  be 
regarded  as  i  single  particle. 


2.1 


NAMKS 


Names  Include  those  which  are  primitive  In  the 
system  as  well  as  user-def lnod.  Names  begin  with  a 
letter  of  the  alphabet  and  contain  letters,  digits 
ami/or  hyphens  (-)  .  Letters  may  be  upper  or  lower 
case  (no  distinction  will  bo  made).  Any  number  of 
characters  may  appear  in  a  user-defined  name  and 
all  that  are  used  will  be  remembered  in  the  name 
diet  ionary . 


Names  are  usually  delimited  by  blanks  or  begin 
or  end  t  tie  line.  However,  other  characters  which  may 
not  appear  in  a  name,  if  they  stand  immediately  adja¬ 


cent  to  the  name  will  also 
name . 

Valid  name  examples: 

FOR 
Vt  ITU 
LIST 
COM 
F4J 


serve  as  a  delimiter  of  the 


for  (same  as  FOR) 
With  (same  as  WITH) 
LI ST- VERT l CAL 
DATA-UASE-NO-3 
H - 


Invalid  name  examples  with  reasons  for  invalidity: 

DATA  BASE  (two  names) 

FILE-NO. -3  (invalid  character.  FILE-NO 

will  be  taken  as  the  name) 
2-4-B  (must  start  with  a  letter) 


2.2  NUMBERS 


Numbers  are  of  two  kinds,  those  which  appear  as 
pnrnmeters  (e.g.  column  numbers)  and  those  which  appear 
as  dal  n  (to  be  compared  to  the  data  base  entries). 

The  first  kind  contains  only  digits  nnd  is  delimited 
by  blanks,  parentheses  or  commas.  An  example  of  a  state¬ 
ment  which  contains  two  numbers  is; 


DECLARE  ITEM  NUM(12,24)  A 


The  latter  kind  of  number  may  also  contain  a  sign 
(+  or  -)  and  a  decimal  point,  however  neither  is  required. 
This  kind  of  number  will  normally  be  enclosed  in  delim¬ 
iters  ('  or  ')  although  they  are  optional  where  the 
context  makes  the  identity  of  the  number  clear.  Examples 
of  this  kind  of  number  are: 

LIST  SALARY  WHEN  EDUCATION  GE  '16'  # 

WITH  GR\DE  EQ  '4'  '5'  *6’  COUNT  # 

'+21.54' 

’-15' 


2.3  DELIMITERS 


The  two  delimiting  characters  for  data  are  the 
prime  (')  and  quotation  mark  (") .  When  used  as  delim¬ 
iters,  they  must  occur  in  pairs,  i.e.  the  one  used  to 
o>en  the  delimited  string  must  also  be  used  to  close 
it.  A  delimited  string  may  contain  one  of  the  delim¬ 
iting  characters  by  using  the  other  as  delimiters. 

For  example: 

'Quotation  mark  (")  ' 

"Prime  (')" 

Any  character  string  (other  than  the  delimiting 
characters)  may  occur  between  delimiting  characters. 

"Picture  #42n" 

No  other  characters  (blanks  included)  may  be 
used  to  delimit  data  strings  (except  in  the  case  of 
numbers,  n'jovo,  where  blank  delimiters  are  optional). 


2.4  STATEMENT  TERMINATOR 


Every  Query  statement  shall  be  terminated  by 
the  Pound  character  (£*)  .  The  #  character  may  only 
be  used  at  the  end  of  the  line  (or  in  a  delimited 
data  string).  I  t'  a  Query  statement,  line  does  not 
end  with  n  #  character,  it  will  be  assumed  that  the 


statement  continues  on  the  next  line. 
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Data  base  lines  also  use  the  #  terminator.  If  a 
data  base  line  does  not  end  with  the  #  character,  it 
will  be  assumed  that  the  next  line  is  a  continuation 
of  (extension  to)  the  current  one. 

The  #  character  may  appear  alone  on  a  line  as 
an  indication  that  data  base  inputs  are  complete  and 
the  next  line  is  to  be  taken  as  a  Query  statement. 

The  #  character  is  not  used  to  terminate  control 
statements  as  described  below. 


2.5  CONTROL  STATEMENT  DESIGNATOR 


A  character  will  be  chosen  at  installation  time 
to  be  the  Control  Statement  Designator.  For  the 
purposes  of  this  document,  that  character  will  be 
assumed  to  be  a  dollar  sign  ($) .  To  be  a  Control 
Statement  Designator,  the  chosen  character  must  occur 
first  on  the  line,  i.e.  the  first  typed  character  of 
the  line.  Control  statements  have  no  standard 
termination  character.  The  #  character  does  not 
terminate  control  statements.  For  example: 

$QUIT  ALL 


2 . 6  BLANKS 


The  exact  count  of  blanks  on  a  line  is  significant 
only  in  the  case  of  input  strings  to  a  data  base.  Other¬ 
wise,  all  groups  of  multiple  blanks  are  treated  as  single 
blanks.  Blanks  are  useful  to  clarify  the  syntax  of 
a  query  statement  especially  as  pertains  to  names  and 
numbers.  However,  the  usual  case  is  that  blanks  (and 
particularly  the  multiple  occurance  thereof)  are  optional. 

The  following  three  statements  will  be  functionally 
equivalent : 

LIST  ENTRY  WHEN  NAME  EQ  ’JOHN  SMITH’  # 

LIST  ENTRY  WHEN  NAME  EQ ' JOHN  SMITH'# 

LIST  ENTRY  WHEN  NAME  EQ  'JOHN  SMITH  '  # 


The  following  shows  the  omission  of  a  blank  which 
makes  the  statement  invalid: 

LIST  ENTRY  WHEN  NAMEEQ  'JOHN  SMITH’  # 

In  this  case,  NAMEEQ  is  taken  as  a  single  particle, 
making  the  syntax  of  the  statement  invalid. 


2.7  PARENTHESES 


The  rules  pertaining  to  parentheses  only  affect 
1  hose  in  the  query  statement  which  do  not  occur  between 
delimiting  characters  or  in  data  base  input  lines. 

In  general,  parentheses  are  used  in  the  query 
statement  to  clarify  conditional  clause  groupings 
that  might  otherwise  be  ambiguous.  Any  conditional 
clause  or  any  combination  of  compound  conditional 
clauses  may  be  enclosed  in  parentheses.  However,  the 
clause  within  the  parentheses  must  be  complete. 

Examples  of  valid  uses  of  parentheses  follow: 

LIST  ENTRY  WHEN (NAME  EQ  'JOHN  SMITH’)  # 

WITH  SEX  EQ  * F'  AND (EYES  EQ  ’BLUE'  OR 

HAIR  EQ  ’BROWN’)  COUNT  # 

The  limit  to  the  number  of  parentheses  which  may 
be  used  in  a  statement  is  sufficiently  generous  that  the 
user  will  seldom,  if  ever,  encounter  it.  The  exact  number 
will  be  a  function  of  installation  but  will  usually  be 
in  the  order  of  fifty  or  more. 

The  reader  will  find  additional  explanation  and 
examples  regarding  the  vise  of  parentheses  in  sections 
5.25  and  7.1. 


3.0 


INPUT  FORMS 


There  are  three  input  formats  which  the  Query 
system  recognizes:  (1)  Query  statement  form,  (2) 
Data  base  entry  form,  and  (3)  Control  statement  form. 


3.1  QUERY  STATEMENT  FORM 


The  Query  statement  form  refers  to  those  query 
statements  which  are  composed  for  the  purpose  of  select¬ 
ing  certain  data  from  the  data  base  to  be  displayed  in 
the  report.  In  addition,  this  form  also  includes  certain 
directives  for  creating  and  naming  a  data  base  and  for 
accepting  data  from  a  card  reader  device. 


3.11  PARTICLE  NAMES  FOR  THE  QUERY  STATEMENT  FORM 


Prepositional  Qualifier 

for  Data  Base  Name:  FOR 

Prepositional  Qualifier 

for  Selection  Clause:  WITH 

WHERE 

WHEN 

Connectives:  AND 

OR 

Negation:  NOT 

Relationals:  GT  (Greater  than) 

GE  (Greater  or  equal  to) 

EQ  (Equal  to) 

LE  (Less  or  equal  to) 

LT  (Less  than) 

NE  (Not  equal  to) 

Reporting  verbs:  LIST 

LIST-VERTICAL  (&  LISTV) 

COUNT 

TOTAL 

AVERAGE 


Adjectives:  NULL 

PRESENT 

SMALLEST 

GREATEST 

FIRST 

LAST 

NEAREST 


Command  verbs:  PRESTORE 

READ-CARDS 

DATA-BASE 

DEFINE 

DECLARE 


DECLARE  Qualifiers:  STR  (String) 

NUM  (Number) 


Three  additional  particle  names  in  the  Query  state¬ 
ment  are  user-defined.  These  include  data  base  names, 
data  base  attribute  names,  and  macro  names.  For  the 
purposes  of  this  document,  three  mnemonics  will  be 
assigned  which  will  always  be  used  to  signify  the  three 
names  as  follows: 


Data  Base  Name: 
Data  Rase  Attribute  Name: 

Macro  Name: 


Dlname 

Attr-Name 

Macro-Name 


The  reader  should  understand  that  wherever  the 
above  three  mnemonics  appear  in  this  document,  some 
user-chosen  name  will  stand  in  its  place. 


3.12  DATA  PARTICLES  TOR  THE  QUERY  STATEMENT  FORM 


Data  particles  in  the  query  statement,  can  be  any 
arbitrary  series  of  characters  enclosed  between  a  pair 
of  delimiting  characters  as  described  in  2.3.  The  data 
will  always  qualify  as  being  String  data  since  this 
refers  to  a  completely  arbitrary  string  of  characters. 
Additionally,  the  data  may  qualify  as  Numerical  data 
if  the  data  consists  only  of  a  number  (nnd  optional 
leading  sign  nnd  decimal  point). 


Some  query  statement  forms  can  accept  the  more 
general  String  data  particle  form  while  others  demand  the 
Numerical  data  particle  form.  In  particular,  the  relat¬ 
ional,  GT,  GE,  LE,  and  LT  can  only  be  used  with  Numerical 
data  particles  (or  with  numerical  Attr-Names) .  Also,  when 
a  data  particle  is  logically  compared  to  a  numerical 
Attr-Name,  the  data  particle  must  be  Numerical .  This 
will  be  discussed  in  much  more  detail  later. 

For  the  present,  two  mnemonics  will  be  used  to 
differentiate  the  two  kinds  of  data  particles.  Keep  in 
mind  that  a  Numerical  data  particle  also  qualifies  as 
a  String  data  particle  but  the  converse  is  generally  not 
true . 


String  Data  Particle: 


'String  Data' 


Numerical  Data  Particle: 


'Numerical  Data' 


3.13  QUERY  STATEMENT  GENERAL  FORMS 


There  are  two  general  forms  for  the  query  statement. 
One  has  the  data  selection  clause  before  the  reporting 
verb,  the  other  has  it  after.  Brackets  denote  optional 
entries  in  the  general  form. 

Form  number  one: 

[FOR  Dlname][Selection  Clause]  Verb  [Attr-Name (s)]  # 
Form  number  two: 

Verb  [Dlname][At tr-Name (s)][Selection  Clause]  # 

In  form  number  one,  if  the  FOR  particle  is  used, 
a  Diname  must  follow  it.  In  either  form,  if  the  Dlname 
is  omitted,  the  most  recently  referenced  Dlname  will  be 
assumed.  If  none  is  valid,  the  statement  will  be 
rejected. 

The  Selection  Clause  refers  to  those  data  compar¬ 
isons  which  cause  the  selection  of  entries  to  be  reported. 
The  composition  of  the  Selection  Clause  and  the  reporting 
possibilities  will  be  discussed  later. 


3.131  FORM  NUMBER  ONE  EXAMPLES 


FOR  EMPLOYEE-LIST  LIST  NAMES  ADDRESSES  # 

TOR  EMPLOYEE-LIST  WITH  ANN-SALARY  GE  '15000’  AND 
HIRE-DATE  LE  '1965'  COUNT  # 

WITH  HIRE-DATE  EQ  '1971'  OR  HIRE-DATE  EQ  '1972'  OR 
HIRE-DATE  EQ  '1973'  LIST  NAMES  # 

WITH  HIRE-DATE  EQ  '1971'  '1972'  '1973'  LIST  NAMES  # 

FOR  ROSTER  WITH  (SEX  EQ  'F'  OR  RACE  NE  'WHITE')  AND 
ANN-SALARY  GE  '15000'  LIST  NAME  AGE  JOB-CLASS  # 


3.132  FORM  NUMBER  TWO  EXAMPLES 

COUNT  EMPLOYEE-LIST  WHEN  ANN-SALARY  GE  '15000' 

AND  HIRE-DATE  LE  '1965'  # 

AVERAGE  STUDENT-BODY  AGE  WHEN  MARITAL- STATUS  EQ  'M'  # 

LIST  EXPENDITURES  CREDITOR  AMOUNT  WHEN  DUE- MONTH  EQ 
'JULY'  AND  DUE-DATE  LE  '20'  U 

TOTAL  DRIVING-RECORDS  ACCIDENTS  WHEN  PRESENT  DISABILITY  # 

LIST  NAME  WHEN  NEAREST  WEIGHT  '170'  # 


3.2 


DATA  BASE  ENTRY  FORM 


Data  base  entries  are  composed  by  concatenating 
lines  of  input  data  until  the  terminal  #  character  is 
encountered.  The  first  character  of  the  data  base 
entry  goes  into  column  one  and  the  following  ones  go 
into  succeedingly  higher  column  numbers  until  the 
terminating  #  is  encountered. 

Data  entries  may  originate  either  at  the 
terminal  or  in  the  form  of  punched  cards.  If  from 
the  terminal,  then  the  terminal  line  length  deter¬ 
mines  the  number  of  characters  (including  trailing 
blatiksl  which  shall  be  concatenated  onto  the  data 
base  entry  i\  r  each  new  line.  Foi*  example,  if  the 
terminal  line  length  is  72  and  the  terminating  # 
character  occurs  in  column  21  of  the  fifth  line,  then 
the  number  of  columns  of  data  in  that  entry  will  be 
(4  X  72)  +  20  -  30S.  The  first  five  characters  typed 
on  the  third  line  would  be  located  in  columns  145 
through  149  of  the  entry.  Thus,  each  entry  of  the 
data  base  can  be  visualized  as  one  long  punched  com¬ 
puter  card  whose  length  can  accomodate  all  the  char¬ 
acters  in  the  entry. 

Data  entries  which  originate  from  punched  cards 
are  composed  by  concatenating  the  contents  of  the 
cards  in  a  similar  manner.  Each  punched  card  will 
be  assumed  to  contain  80  characters  unless  given  a 
smaller  number  in  the  READ-CARDS  verb,  described  below. 

The  only  characters  which  are  not  appropriate 
in  a  data  base  entry  are  two  dollar  signs  ($$)  in 
columns  one  and  two  (which  are  used  to  signify  an 
end-of-file  to  the  card  reader). 

Total  possible  length  of  any  single  data  entry 
is  determined  at  the  time  the  system  is  installed  by 
the  values  chosen  for  certain  of  the  parameters.  It 
will  usually  be  sufficiently  generous,  in  the  order  of 
1,500. 

Lengths  of  data  base  entries  may  be  allowed  to 
vary.  If  uniformity  is  required  for  any  subsequent 
query  search,  a  trailing  blank  fill  in  the  entry  will 
be  assumed. 

Exit  from  the  data  entry  mode  is  accomplished 
by  typing  (or  punching)  a  #  character  in  column  one, 
making  it  the  only  character  in  the  entry. 


3.3  CONTROL  STATE  ENTRY  FORM 


Control  statements  begin  with  a  $  character  in 
column  one  and  are  typed  in  the  format  prescribed  for 
each  statement.  Only  the  number  of  blanks  are  optional 
requiring  at  least  one  for  each  blank  shown  in  the 
.statement  form,  below. 

Control  statements  may  be  entered  only  at  the 
terminal  (not  from  the  card  reader)  and  only  while 
he  terminal  is  accepting  query  statements  (not  while 
it  is  in  the  data  entry  mode).  If  a  control  statement 
is  mistakenly  entered  while  the  terminal  is  in  the 
data  entry  mode,  that  input  line  will  be  concatenated 
to  the  data  entry. 

Control  statements  are  generally  only  used  by 
the  system  operator,  except  for  $OUT,  the  user  sign  off 

Following  the  execution  of  the  control  statement, 
the  terminal  is  left  in  the  query  statement  mode, 
except  in  the  case  of  a  system  shutdown  ($QUIT  ALL) 
in  which  case  all  files  and  devices  would  be  detached 
and  program  execution  would  stop. 


3.4  INPUT  DEVICE  FORMS,  TERMINAL  VS.  CARDS 

In  general,  input  forms  for  the  terminal  and  for 
punched  cards  are  identical.  Exceptions  are  the  $$ 
(end-of-f ile)  characters  in  columns  one  and  two  of 
punched  cards  which  have  no  meaning  on  the  terminal, 
and  Control  Statements  which  are  not  allowed  from 
punched  cards.  Otherwise,  the  conventions  apply  to 
either . 


,,  ... 
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4.0 


DATA  BASE  CREATION 


Data  bases  may  either  be  created  or  extended  by 
use  of  the  DATA-BASE  verb.  Also,  following  the  input 
of  the  DATA-BASE  verb,  the  input  mode  is  switched  to 
data  entry. 


4.1  DECLARING  A  NEW  DATA  BASE 


A  new  data  base  is  declared  by  entering  the  line 
(in  the  query  entry  mode): 

DATA-BASE  Dlname  # 

The  chosen  Dlname  must  be  different  from  any 
name  presently  catalogued  on  the  system.  Following 
this  entry,  the  next  input  will  be  in  the  data  entry 
mode,  creating  the  data  entries  for  the  named  data 
base . 


When  the  data  base  is  complete,  or  the  completion 
is  to  be  delayed  until  later,  enter  a  #  character  as 
the  first  and  only  character  of  the  entry.  Entry  mode 
will  switch  back  to  query  form. 

A  data  base  may  be  declared  using  the  DATA-BASE 
command  without  any  entries  by  exiting  with  the  # 
ch  iracter  immediately  after  naming  the  data  base.  This 
technique  can  be  useful  for  naming  a  data  base  on  the 
terminal  which  will  be  created  from  punched  cards. 


4.2  ADDING  TO  A  NAMED  DATA  BASE 


By  using  the  same  command  as  above,  i.e.: 
DATA-BASE  Dlname  # 

where  the  Dlname  already  exists,  entries  may  be  added 
to  the  named  data  base.  If  this  situation  occurs  at 
the  terminal,  a  confirmation  is  required,  i.e.  the 
system  will  ask: 


ADD  TO  THIS  DATA  BASE?  (Y/N) 
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If  tho  wrong  name  has  been  chosen,  the  user  will  have 
opportunity  to  correct  it.  No  confirmation  opport¬ 
unity  is  given  if  the  DATA-BASE  command  comes  from 
a  punched  card. 

Data  bases  can  be  arbitrarily  long,  having  as 
many  entries  as  the  storage  medium  will  allow. 


4.3  ADDING  TO  THE  CURRENT  DATA  BASE 


By  omitting  the  Diname  from  the  command  form, 
the  user  can  add  entries  to  the  currently  active 
data  base.  The  command  form  would  be: 

DATA-BASE  # 

If  a  data  base  is  currently  active  through  previous  use, 
input  mode  would  then  switch  to  data  entry  form  and  the 
next  input  would  create  an  additional  entry  for  the 
active  data  base.  This  command  form,  in  combination 
with  that  shown  in  4.1  above,  allows  the  user  to  name 
a  data  ba  e  at  the  terminal  and  fill  it  with  data  from 
punched  cards.  The  sequence  of  commands  would  appear 
as  follows: 


DATA-BASE  Diname  # 

# 

READ-CARDS  Filename  # 

The  new  data  base  would  thus  be  named  and  immed¬ 
iately  terminated.  Input  would  be  switched  to  the  card 
entry  format  because  of  the  READ-CARDS  command  verb. 

Then,  in  order  that  the  entries  on  the  cards  become  assoc¬ 
iated  with  the  newly  named  data  base,  no  data  base  is  named 
on  the  cards.  Rather,  the  statements  on  the  cards  lely  on 
the  default  condition,  i.e.  that  the  data  base  to  be  used 
will  be  the  one  most  recently  named.  Thus,  if  the  cards 
hold  entries  for  the  data  base,  the  first  ca rH  would 
contain  the  command  verb: 

DATA-BASE  # 

Notice  that  it  does  not  name  the  data  base,  using  instead 
the  most  recently  named  one.  The  following  entries  would 
then  contain  data. 
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DATA  BASE  ORGANIZATION 


Assuming  that  tho  new  data  base  has  been  named 
wi'h  the  DATA-BASE  command  vorb  and  the  user  is  now 
in  the  data  entry  mode,  roady  to  put  tho  data  into  the 
data  base,  tills  section  describes  how  to  organize  tho 
entries  so  that  the  data  base  can  be  easily  searched  at 
a  later  time  for  on-line  retrieval. 

Recall  from  section  3.2  that  the  rules  for  building 
da- a  entries  from  the  terminal  art*  exactly  the  same  as  from 
punched  cards  with  tho  only  difference  being  the  length 
of  tin*  line*  (number  of  columns)  that  each  device  sends. 

Recall,  too,  from  section  3.2  that  tho  entry 
should  bo  visualized  ns  a  very  long  punched  card  that 
may  have  upwards  of  1,500  columns.  Many  of  those  columns 
will  normally  be  blank.  However,  each  of  those  1,500- 
column  entries  become  one  entry  in  the  data  base,  where 
tho  data  base  name  can  refer  to  a  collection  of  hundreds 
or  thousands  of  these  entries. 

It  will  often  require  several  linos  (or  punched 
ca *ds)  to  make  up  n  single  entry.  The  end  of  the  entry 
is  indicated  by  the  terminal  ft  character. 

The  entry  itself  will  be  made  up  of  "fields"  of 
data  where  each  field  is  n  series  of  columns  that  are 
dedicated  to  a  particular  kind  of  data.  Using  a  DECLARE 
ve*b,  the  field  gets  nnmod,  and  that  bocomes  the  At  trihut  o 
Name  (Attr-Name)  for  that  data.  (See  also  section  8.5 
regarding  the  DECLARE  verb). 

For  example,  suppose  it  was  decided  to  make  columns 
one  through  20  to  be  tho  "first  name"  field,  and  columns 
21  through  *10  tho  "last  name"  field.  Presumeably,  then, 
each  entry  in  tho  data  base  would  contain  data  on  a 
particular  individual.  Each  entry  would  correspond  to 
n  different  person.  Then,  for  each  now  entry,  the  first 
name  would  go  into  columns  one  through  20  and  tho  last 
name  in  columns  21  through  40.  Unused  columns  within 
tie  sc  fio'ds  would  he  left  blank.  However  j  the  field 

t  l.e  declared  sufficiently  long  to  accomodate  any  name 
ught  go  into  the  data  base  because  it  would  create 
•  i  m*;  to  have  any  name  extend  beyond  its  field.  We 
-  ,  tioose  to  declare  three  attribute  names  for  those 

•  •  •  f  «•!<!*: 


DECLARE  FIRST-NAME  STR(1,20)  # 
DECLARE  LAST-NAME  STR(21,40)  ft 
DECLARE  FULL-NAME  STR(1,40)  ft 


Here,  we  have  essentially  identified  three  fields,  1-20, 
21-40,  and  1-40,  with  an  attribute  name  for  each  field. 
Having  decided  on  this  organization  for  the  data  base, 
it  now  becomes  important  to  be  sure  that  the  appropriate 
data  are  entered  in  the  appropriate  columns.  If  there 
are  multiple  lines  (or  cards)  per  entry,  then  columns 
one  through  40  are  always  (and  only)  on  the  first  of 
those  lines  (or  cards). 

i 

To  complete  the  example,  suppose  that  columns  81 
through  83  are  chosen  for  the  individual's  age.  The 
DECLARE  verb  might  read: 


DECLARE  AGE  NUM(81,83)  # 


where  AGE  would  be  the  Attr-Name  for  that  field.  Now, 
suppose  that  three  entries  are  to  be  added  to  the  data 
base  where  each  entry  contains  the  first  and  last  names 
and  age.  Notice  that  the  skipped  columns  41-80  are  of 
no  concern.  If  the  card  length  is  80  columns,  then  the 
data  entry  inputs  might  look  like  the  following: 


JOHN  JONES 

39  if 

ANN  SMITH 

27  # 

GEORGE  WASHINGTON 

105  rr 


Now,  let's  repeat  that  data  base  in  full,  showing 
the  entire  deck  as  it  might  be  submitted  to  the  Query 
system: 

DATA-BASE  NAME-AGE-LIST  # 

JOHN  JONES 

39  if 

ANN  SMITH 

27  a 

GEORGE  WASHINGTON 

105  a 

M 

rr 

DECLARE  F  rRS'.’-NAME  STR(1,20)  if 
DECLARE  LAST-NAME  STR(21,40)  ft 
DECLARE  FULL-NAME  STR(1,40)  # 

DECLARE  AGE  NUM(81,83)  if 

$$ 


Note  that  the  final  line  ($$)  is  necessary  only  if  the 
input  is  coming  from  punched  cards;  if  from  the  terminal, 
that  line  can  be  omitted. 

In  summary,  the  following  considerations  go  into 
creating  a  data  base: 

•  The  data  base  must  be  named  in  a  DATA-BASE 
command  verb 

•  Data  fields  (column  sequences)  must  be  chosen 
for  each  attribute  (type  of  datum)  in  the 
data  base 

•  Data  entries  must  be  constructed  in  such  a  way 
that  appropriate  data  occur  in  the  proper  columns 
to  match  the  chosen  data  fields 

•  A  single  #  line  must  be  included  to  exit  from 
the  data  entry  mode 

•  DECLARE  statements  must  name  each  of  the  chosen 
data  fields  and  indicate  whether  they  are 
arbitrary  strings  of  data  (STR)  or  numerical 
data  (NUM) 

0  If  the  data  entry  is  from  punched  cards,  a  final 
$$  card  must  be  added  to  terminate  the  deck 

Once  entered,  the  data  base  may  be  used  for  on-line 
retrieval,  or  it  may  be  enlarged  by  the  addition  of 
new  data  entries  and/or  new  DECLARE  statements.  The 
number  of  attribute  names  which  may  be  declared  is 
limited  only  by  the  amount  of  working  space  in  the 
Query  system. 
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5.0  THE  QUERY  STATEMENT 

Section  3.1  has  already  discussed  the  two  basic 
general  forms  for  the  query  statements.  Both  forms 
serve  the  same  purpose.  They  just  provide  optional 
formats  for  the  query. 

The  query  statement,  regardless  of  the  form 
chosen,  contains  five  essential  elements: 

•  Identification  of  the  data  base  to  be  used 
in  the  data  search 

•  Selection  clause  to  determine  which  of  the 
data  base  entries  are  pertinent  to  the 
current  query  report 

•  Reporting  verb  to  designate  the  kind  of 
information  desired  and  how  it  should  be 
displayed 

•  Report  clause,  made  up  of  a  list  of  those 
Attr-Names  which  designate  the  data  from 

the  selected  entries  that  are  to  be  displayed 

•  Terminator  character  (#)  which  marks  the  end 
of  a  query  statement,  possibly  a  multi-line 
one. 

Of  the  above  five  elements,  only  the  reporting 
verb  and  the  termination  character  are  mandatory  in 
the  query  statement.  Default  interpretations  exist 
for  the  other  three  in  most  cases. 

Note  that  the  above  five  elements  are  present 
in  both  of  the  general  forms  as  shown  in  section  3.13. 
Only  the  order  is  different. 

Consideration  will  now  be  given  to  each  of  the 
above  five  elements. 


5.1  DATA  RASE  IDENTIFICATION 


The  data  base  to  be  used  in  the  search  to  satisfy 
a  query  statement  is  identified  by  its  name,  i.e.  the 
Dlname.  The  Diname  is  made  up  by  whoever  creates  the 


data  base  as  described  in  section  4.  The  rules  for 
choosing  a  name  are  described  in  section  2.1. 

The  Dlname  refers  to  dozens,  hundreds  or  thousands 
of  entries,  depending  on  the  size  of  the  data  base,  each 
of  which  may  be  several  hundred  characters  in  length. 

It  is  this  data  base  which  will  be  searched,  entry-by¬ 
entry,  to  determine  which  of  the  entries  qualify  for 
the  qviery  statement  report. 

The  Dlname  is  the  second  name  to  appear  on  the 
query  statement  line.  For  form  number  one  (see  section 
3.13),  the  Dlname  follows  the  word,  FOR.  For  form 
number  two,  it  follows  the  reporting  verb. 

If  th  Dlname  is  omitted,  the  most  recently  named 
data  base  will  be  used.  If  none  is  currently  active, 
an  error  message  will  so  inform  the  user.  Note  that 
the  omission  of  the  Dlname  in  form  number  one 
implies  that  the  word,  FOR,  must  also  be  omitted.  In 
form  numbei'  two,  the  Dlname  may  be  omitted  without 
changing  the  remainder  of  the  statement. 


5.2  THE  SELECTION  CLAUSE 


The  selection  clause  is  the  source  for  most  of 
the  variety  in  query  statements.  It  is  this  clause 
that  determines  which  of  the  data  base  entries  will 
qualify  for  the  report.  The  selection  clause  portion 
of  the  query  statement  resembles  "IF"  statement 
constructions  in  several  of  the  computer  programming 
languages . 


5.21  COMPARISON  OF  SELECTION  CLAUSES  IN  THE  TWO  FORMS 


Selection  clause  construction  rules  are  nearly 
identical  for  the  two  query  statement  foi'ms  (in  section 
3.13).  The  only  difference  is  in  the  use  of  the 
primitive  words,  WITH,  WHERE  and  WHEN.  Whereas  the 
words,  WITH  and  WHERE  are  used  (interchangeably)  in 
form  one,  WHEN  is  used  in  form  two.  They  can  occur 
in  the  same  positions  in  the  selection  clause,  and 
the  choice  of  any  one  of  the  three  makes  no  difference 
in  the  query  statement. 


Therefore,  in  the  following  illustrations  of  the 
selection  clause,  WITH  will  normally  be  the  word  used, 
but  the  reader  should  understand  that  either  WITH  or 
WHERE  can  be  used  in  form  one,  and  WHEN  can  be  used 
in  form  two  with  identical  results. 


f>.  22  NATURE  AND  PURPOSE  OF  THE  SELECTION  CLAUSE 


The  selection  clause  is  one  of  the  most  critical 
elements  of  the  entire  query  system.  If  the  user  chose 
to  view  all  of  the  data  in  the  data  base,  no  query 
system  would  be  necessary;  he  copld  view  the  listing 
before  it  was  entered  into  the  system.  The  purpose 
of  the  query  system  is  to  allow  the  user  to  system¬ 
atically  select  only  those  data  which  are  relevant  for 
the  occasion  without  being  innundated  with  it  all. 

The  selection  clause  is  used  to  make  that  deter¬ 
mination  of  whether  a  particular  entry  is  relevant  for 
the  report  being  requested  by  the  user.  If  judged 
relevant,  the  reporting  verb  clause  will  determine  which 
data  fields  of  that  entry  to  display.  If  not,  the 
entry  will  be  passed  by. 

The  selection  clause  contains  a  logical  comparison 
of  data  fields.  The  comparison  is  judged  either  "true” 
or  "false."  If  judged  "true,"  the  entry  qualifies, 
otherwise  it  doesn’t. 

The  "true/false"  comparison  is  often  a  combina¬ 
tion  of  several  "true/false"  comparisons  where  there 
are  different  alternatives  given  under  which  the  entry 
might  qualify.  Therefore,  using  AND,  OR,  NOT  and 
parentheses  to  formulate  the  comparisons  of  the  data, 
it  will  be  shown  that  the  possibilities  are  virtually 
limitless  for  selecting  only  those  data  that  are 
pertinent  to  any  imaginable  reporting  need  while  also 
insuring  (hat  no  data  are  overlooked. 

Therefore,  the  selection  clause  is  a  comparison 
of  drta  that  begins  with  the  word,  WITH,  or  the  word, 
WHEN,  in  forms  one  or  two  of  the  query  statement, 
respt cti\ ely .  The  following  are  simple  selection  clauses 

WITH  BREED  EQ  ’ TERRIOR’ 

WITH  VALUE  GT  ’4.5’ 

WHEN  JOB-CLASS  EQ  ’NON-EXEMPT’ 
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COMPARISON  OF  DATA 


The  important  elements  of  the  comparison  of  data 
are  the  attribute  names  (Attr-Narae) ,  the  data  strings 
and  the  relationals. 

The  Attr-Name  tells  where  to  find  the  data  for 
the  comparison  within  the  data  base  entry,  and  what 
kind  of  data  to  expect  (arbitrary  strings  of  characters 
or  numerical  data) .  The  Attr-Narae  is  chosen  at  the 
time  the  data  base  is  created  via  the  DECLARE  statement, 
and  data  are  entered  into  the  data  base  in  the  data 
fields  specified  by  the  Attr-Name  declaration.  (See 
section  4.4  fr»r  the  data  base  organization). 

The  data  strings,  enclosed  within  delimiters, 
designate  the  characters  to  be  used  in  the  comparison 
with  those  in  the  Attr-Name  data  fields.  (See  sections 
2.3  and  3.12  regarding  the  use  of  delimiters). 

The  relationals  determine  how  the  data  are  to  be 
compared,  and  what  constitutes  a  "true"  or  "false" 
result.  The  relationals  are  listed  in  section  3.11: 

GT,  GE,  EQ,  LE,  LT  and  NE. 

If  the  comparison  is  between  data  strings  which 
are  not  numerical,  only  the  EQ  and  NE  apply  since  the 
strings  either  match  or  they  don’t.  However,  if  the 
strings  are  numerical,  there  can  also  be  a  greater  than 
or  less  than  relationship,  and  any  of  the  six  relationals 
are  valid. 

The  comparison  format  is  simply  any  two  data 
string  designations  separated  by  a  relational.  Thus, 
the  following  are  all  valid  examples  of  data  comparisons: 

AGE  GE  ’65’ 

RANK  EQ  ' E4 ’ 

LAST-NAME  EQ  ’WASHINGTON' 

CURRENT-SALARY  LT  BEGINNING-SALARY 
SEX  EQ  ’MALE* 

TEMP  LT  ’-20.5' 

' 4 1  LT  ’ 5 ' 


Note  that  the  last  comparison  is  valid  but  trivial 
since  it  will  always  be  true  and  makes  no  reference  to 
the  data  base.  This  kind  should  be  avoided.  In  each 
of  the  others,  at  least  one  side  of  the  comparison  is 
an  Attr-Name,  referring  to  the  data  base.  In  one  case, 
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both  sides  of  the  comparison  has  Attr-Names,  indicating 
a  comparison  of  two  data  fields  within  the  data  base 
entries.  It  is  usually  apparent  which  Attr-Names  are 
numeric  and  which  are  not,  indicated  both  by  the 
delimited  data  strings  in  the  comparison  and  by  the 
relational  being  used.  Wrong  comparisons  will  inval¬ 
idate  the  query  statement.  The  following  are  some 
examples  of  obviously  wrong  comparisons: 

AGE  GE  ’65  YEARS' 

RANK  LE  ’ E4 ' 

LAST-NAME  GT  'WASHINGTON' 

INITIAL  GT  'J' 

The  relationals,  GT,  GE,  LE  and  LT,  must  only  be 
used  to  compare  strings  of  data  which  name  numerical 
quantities.  No  lelative  value  is  given  to  letters  of 
the  alphabet. 

It  will  also  be  necessary  to  understand  how  blanks 
are  treated  in  the  comparison.  The  general  rule  is  that 
leading  and  trailing  blanks  are  ignored,  and  embedded 
sequences  of  blanks  are  treated  as  single  blanks.  (See 
also  section  2.6).  For  example,  using  the  data  base  in 
section  4.4,  each  of  the  following  would  be  a  "true" 
comparison: 

FULL-NAME  EQ  'GEORGE  WASHINGTON' 

FULL-NAME  EQ  '  GEORGE  WASHINGTON  ' 
FULL-NAME  EQ  '  GEORGE  WASHINGTON' 

However,  the  following  would  not  be  counted  "true"  since 
no  comma  appears  in  the  data  base: 

FULL-NAME  EQ  'GEORGE  ,  WASHINGTON’ 

This  constitutes  the  basic  comparison  format  for 
the  selection  clause.  The  variety  of  Attr-Names  and 
data  strings  is  virtually  infinite;  the  relationals  are 
limited  to  the  six  that  are  listed.  The  discussion  that 
follows  will  show  how  these  comparisons  can  be  compounded 
to  make  the  selection  as  specific  as  desired. 
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5.24  SIMPLE  SELECTION  CLAUSES 


Recall  that  the  selection  clause  within  the  quex*y 
statement  functions  to  determine  whether  the  data  in 
a  given  data  base  entry  meet  the  conditions  specified 
by  the  user  so  that  the  entry  should  be  used  for  the 
report,  or  whether  it  fails,  in  which  case  the  entry 
would  be  passed  by  for  this  report. 

The  simple  form  of  such  a  selection  clause 
consists  of  a  preposition  (WITH  or  WHEN)  and  a  com¬ 
parison.  Several  simple  selection  clauses  have 
already  been  illustrated,  including  those  at  the  end 
of  section  5.22.  In  section  5.23,  several  comparisons 
were  listed.  By  adding  the  preposition  WITH  (or  WHEN) 
to  the  beginning  of  these  comparisons,  they  would  become 
valid  selection  clauses.  Thus,  a  simple  selection  clause 
would  be: 

WITH  AGE  GE  ’65’ 


5.25 _ COMPOUND  SELECTION  CLAUSES 


Compound  selection  clauses  differ  from  simple 
selection  clauses  only  in  the  number  of  comparisons 
being  made,  where  the  comparisons  are  joined  by  the 
connectives,  AND  or  OR.  Also,  compound  selection 
clauses  can  be  further  clarified  by  grouping  comparisons 
within  parentheses. 

Compound  selection  clauses  permit  the  selection 
criteria  to  consider  more  than  one  data  field  in  the 
data  base  entry  before  that  entry  is  used  in  the  report. 
For  example,  suppose  the  report  is  to  consist  of  only 
male  drivers  under  25  years.  The  selection  clause 
might  be: 

WITH  SEX  EQ  ’M'  AND  AGE  LT  *25’ 

Note  that  the  data  base  must  be  using  1 M’  and  '  F’  for 
male  and  female  instead  of  spelling  them  out.  Because 
of  the  AND  connective,  both  comparisons  must  be  "true" 
in  order  for  the  entry  to  qualify  for  the  report. 

A  third  comparison  might  be  of  interest:  male,  under  25 
and  three  or  more  accidents.  That  selection  clause  might 
read : 
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WITH  SEX  EQ  'M'  AND  AGE  LT  '25*  AND  ACCIDENTS  GE  '3' 

As  the  selection  clause  grows  in  length,  it  soon  becomes 
apparent  why  multiple  lines  are  needed  for  the  full 
query  statement.  Recall,  too,  that  the  selection  clause 
is  just  one  of  the  elements  in  the  query  statement  as 
listed  in  section  5.0. 

The  OR  connective  permits  alternative  criteria 
for  the  entry  to  qualify.  For  example,  suppose  the 
interest  was  in  those  who  were  under  25  or  over  65, 
then  the  selection  clause  might  read: 

WITH  AGE  LT  '25'  OR  AGE  GT  '65' 

As  with  the  AND  connective,  so  several  comparisons  can 
bo  joined  with  the  OR  connective.  So  long  as  a  series 
of  comparisons  are  joined  with  AND  connectives  (or  OR 
connectives),  there  is  no  confusion  about  the  intent  of 
the  selection  clause.  However,  an  element  of  confusion 
can  be  introduced  if  both  connectives  appeal’  in  the 
same  selection  clause,  as  it  is  often  desirable  to  do. 
Consider  the  selection  clause: 

WITH  SiX  EQ  'M'  AND  AGE  LT  '25'  OR  AGE  GT  '65' 

It  is  clear  that  males  under  25  years  are  in  view,  but 
what  about  the  "over  65"  bracket,  are  they  only  males 
or  both  sexes?  A  heierarchy  rule  is  consistently  applied 
in  cases  of  this  sort  which  always  causes  AND  conditions 
to  be  satisfied  before  OR  conditions  where  there  is  a 
choice.  However,  if  part  of  the  clause  is  enclosed  in 
parentheses,  the  parenthesized  portion  will  be  satisfied 
first.  Consider  what  effect  this  rule  has. 

In  the  above  example,  since  the  AND  condition  is 
satisfied  first,  the  SEX  comparison  has  no  bearing  on 
the  AGE  GT  '65'  comparison  so  all  over  65  are  in  view. 

If  the  converse  had  been  true,  that  the  OR  condition 
was  satisfied  first,  then  the  two  AGE  comparisons  would 
have  been  made  before  the  comparison  was  made  for  the 
sex;  then  only  the  males  would  have  been  in  view. 

Suppose  the  intention  was  to  consider  only  the 
males  in  both  age  groups.  Then  either  of  the  following 
two  selection  clauses  would  do  the  job: 

WITH  SEX  EQ  'M'  AND  AGE  LT  '25'  OR  SEX  EQ  'M'  AND 

AGE  GT  '65' 

WITH  SEX  EQ  'M'  AND  (AGE  LT  '25'  OR  AC.E  GT  '65') 


The  first  of  the  two  illustrations  combines  the  sex 
comparison  with  each  of  the  two  age  groups.  The  second 
combines  a  single  sex  comparison  with  a  parenthesized 
grouping  which  contains  the  two  age  group  comparisons. 

Both  selection  clauses  have  exactly  the  same  meaning. 
However,  the  second  is  preferred  because  the  efficiency 
of  the  search  will  be  directly  related  to  the  number 
of  comparisons  which  must  be  made.  There  are  four  and 
three  comparisons,  respectively,  in  the  two  illustrations. 

Notice  in  the  second  illustration,  the  parenthesized 
expression  occupies  the  place  in  the  selection  clause 
that  a  simple  comparison  would  normally  occupy.  This 
will  always  be  true,  even  when  the  parenthesized 
expression  contains  other  parenthesized  expressions 
within  it.  'll. ere  is  no  practical  limit  to  the  complex¬ 
ity  of  the  selection  clause  which  may  be  constructed 
by  joining  comparisons  with  AND  and  OR  connectives, 
and  enclosing  any  of  these  in  parentheses. 

Consider  an  example  presented  earlier  in  this 
section  but  with  the  addition  of  the  "over  65"  age 
group: 


WITH  SEX  EQ  ’ M'  AND  (AGE  LT  '25’  OR  AGE  GT  ’65’) 

AND  ACCIDENTS  GE  ’3’ 

Now  let’s  add  a  third  age  group  to  the  above,  the  35-40 
age  group: 

WITH  SEX  EQ  'M'  AND  (AGE  LT  ’25'  OR  (AGE  GE  ’35' 

AND  AGE  LE  ’40’)  OR  AGE  GT  ’65’)  AND  ACCIDENTS 
GE  ’3’ 

Actually,  because  of  the  heierarchy  rule  (AND  before  OR), 
the  inner  set  of  parentheses  would  not  be  necessary. 
However,  it  doesn't  hurt  to  include  them  because,  if 
nothing  else,  it  adds  to  the  clarity  of  the  statement. 

Continuing  to  modify  our  example,  suppose  the 
test  is  still  to  be  made  on  the  same  age  groups  of  males, 
but  instead  of  combining  the  test  with  the  number  of 
accidents,  we  wish  to  know  if  the  male  drivers  are 
either  in  those  age  groups  or  have  three  or  more  accidents 

WITH  SEX  EQ  'M'  AND  ((AGE  LT  '25'  OR  (AGE  GE  ’35’ 

AND  AGE  LE  '40')  OR  AGE  GT  '65')  OR 
ACCIDENTS  GE  '3') 
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You  can  see  that  the  solection  clause  can  take 
into  consideration  any  desired  combination  of  the  data, 
but  also  soon  becomes  somewhat  diffieult  to  keep  the 
original  intention  clear.  A  "MACRO"  capability  will 
be  presented  in  section  7.0  which  will  permit  the 
composing  of  incredibly  complex  selection  clauses,  yet 
they  will  be  very  clear  and  relatively  easy  to  work  out. 
However,  one  should  keep  in  mind  that,  as  the  complexity 
increases,  so  does  the  processing  time.  Therefore,  the 
selection  clause  should  be  only  complex  enough  to  achieve 
the  desired  report. 

In  summary,  if  three  dots  (...)  can  be  taken  to 
represent  an  arbitrary  comparison  of  data,  then  a 
compound  selection  clause  can  be  of  the  form: 

WITH  ...  AND  ...  OR  ...  AND  ...  OR  ...  etc. 

The  AND  and  OR  connectives  can  be  in  any  order  or  com¬ 
bination.  Additionally,  a  parenthesized  expression 
can  occupy  the  place  of  any  of  the  three  dots  (...), 
where  the  parenthesized  expression  is  of  the  form: 

(...  AND  ...  OR  ...  AND  ...  OR  ...  etc.) 

And  other  parenthesized  expressions  can  be  substituted 
for  any  or  all  of  the  three  dots  (...)  in  the  above 
parenthesized  expression,  and  so  on. 


5.26  THE  USE  OF  ADJECTIVES  IN  THE  SELECTION  CLAUSE 


The  selection  clause  adjectives  are:  NULL,  PRESENT, 
SMALLEST,  GREATEST,  FIRST,  LAST,  and  NEAREST.  The 
adjectives  are  used  in  the  comparison  part  of  the 
selection  clause  instead  of  the  relational.  They 
precede  the  Attr-Name  they  modify.  Some  data  comparisons 
using  the  adjectives  might  be: 

NULL  DEGREE  (No  data  in  the  DEGREE  data  field) 

PRESENT  DEGREE  (Any  data  in  the  DEGREE  data  field) 

SMALLEST  SALARY 

GREATEST  SALARY 

FIRST  RECRUIT 

LAST  RECRUIT 

NEAREST  CAREER-YEARS  ’25’ 

The  above  compai'isons  can  be  compounded  using  AND  and  OR 
connectives  just  as  the  other  data  comparisons. 


Note  that  the  NULL  adjective  designates  a  data 
field  which  contains  nothing  but  blanks.  This  would 
be  equivalent  to  the  comparison: 

DEGREE  EQ  ’  ' 

where  the  empty  data  string  signifies  an  empty  DEGREE 
dal  a  field . 

The  PRESENT  adjective  signifies  just  the  opposite, 
that  some  data  (any  data)  exist. 

Note,  also,  that  the  adjectives,  SMALLEST,  GREATEST 
and  NEAREST  imply  that  the  data  field  to  which  they  are 
referring  is  numeric. 


5.'.!7  NEGATED  COMPARISONS  IN  THE  SELECTION  CLAUSE 


The  NOT  adjective  can  be  used  to  negate  any 
comparison .  When  used,  the  NOT  precedes  a  left  paren¬ 
thesis.  Thus,  it  might  be  a  single  comparison  or 
compounded  comparisons  within  the  parentheses. 

The  NOT  adjective  negates  the  interpretation  of 
the  comparison.  Having  the  parenthesized  comparison (s) 
in  mind,  the  NOT  adjective  might  be  thought  of  as 
"Anything  other  than  ...".  For  example,  building  on 
a  previous  illustration: 

WITH  SEX  EQ  ' M*  AND  NOT  (AGE  LT  '25'  OR  AGE  GT  '65') 

By  including  the  NOT  adjective,  the  group  in  view  is  now 
changed  from  males  under  25  and  males  over  65  to  males 
in  the  25-65  age  bracket. 


5.28  ABBREVIATED  "OR"  COMPARISONS 


It  is  often  desirable  to  compare  an  Attr-Name 
to  several  data  sti'ings  in  a  compound  OR  relationship. 

One  such  example  follows: 

WITH  CITY  EQ  'WASHINGTON,  D. C. '  OR  CITY  EQ  'CHICAGO' 
OR  CITY  EQ  'LOS  ANGELES’  OR  CITY  EQ  'ATLANTA'  OR 
CITY  EQ  ' NEW  YORK’ 


A  special  abbreviation  exists  for  the  kind  of 
compound  OR  clause  shown  above  which  is  functionally 
equivalent  but  much  shorter: 

WITH  CITY  EQ  ’WASHINGTON,  D.C. ’  ’CHICAGO’ 

’LOS  ANGELES’  ’ATLANTA’  ’NEW  YORK' 

Thus  abbreviated,  the  various  data  strings  stand 
in  an  OR  relationship  to  one  another,  assuming  that  the 
comparison  portion  (e.g.  CITY  EQ)  is  repeated  for  each 
data  string.  In  other  words,  between  each  data  string 
should  be  assumed  a  repeat  of  OR  CITY  EQ.  Of  the 
repeated  portion,  the  OR  is  constant  for  all  such 
abbreviations  and  the  CITY  EQ  portion  would  be  a  repeated 
copy  of  whichever  Attr-Name  and  relational  headed  the 
clause . 

The  above  abbreviation  also  holds  true  for 
numeric  Attr-Names  and  data  strings. 


5.29  SELECTION  CLAUSE  VARIATIONS 


It  is  permissible  to  repeat  the  WITH  or  WHERE 
preposition  (WHEN,  if  form  two  of  the  query  statement) 
after  any  AND  or  OR  connective.  The  effect  of  adding 
this  preposition  is  the  same  as  if  parentheses  were 
inserted  at  that  point.  For  example: 

WITH  SEX  EQ  ’M'  AND  WITH  AGE  LT  ’25’  OR  AGE  GT  ’65’ 
This  selection  clause  is  equivalent  to  the  following: 

WITH  SEX  EQ  'M'  AND  (AGE  LT  ’25'  OR  AGE  GT  ’65’) 

It  is  also  permissible  to  repeat  the  WITH  or  WHERE 
preposition  (WHEN,  if  form  two)  in  place  of  the  con¬ 
nective.  If  this  option  is  used,  the  AND  connective  is 
assumed.  In  the  first  example  in  this  section  where 
the  "AND  WITH"  appears,  it  would  have  been  equally 
permissible  to  omit  the  AND  as  follows: 

WITH  SEX  EQ  'M'  WITH  AGE  LT  ’25'  OR  AGE  GT  '65' 

Or  equivalently: 

WITH  SEX  EQ  'M'  WHERE  AGE  LT  '25'  OR  AGE  GT  '65' 


Or,  if  it  appeared  in  the  second  form: 

WHEN  SEX  EQ  'M'  WHEN  AGE  LT  ’25’  OR  AGE  GT  ’65’ 

If  there  are  multiple  uses  of  the  WITH,  WHERE  and 
WHEN  prepositions,  then  the  parenthesized  enclosure  which 
opens  at  the  preposition  closes  at  the  next  preposition. 
Thus,  the  interpretation  of  the  above  example  would  be: 

WHEN  (SEX  EQ  'M')  AND  (AGE  LT  '25'  OR  AGE  GT  ’65’) 

Note  that  the  ’’AND"  was  inserted  in  the  explanation  because 
"AND  WHEN"  is  assumed  since  "WHEN"  appeared  alone,  and 
tht'  "WHEN"  then  was  dropped  out  and  replaced  with  a 
parenthesized  enclosure. 

There  is  no  particular  processing  advantage  to 
either  of  the  above  variations.  Rather,  it  is  mainly  a 
matter  of  user  preference. 


5.3  THE  REPORTING  VERB 


The  reporting  verbs  have  been  listed  in  section 
3.31.  The  positions  in  the  query  statement,  depending 
on  form,  have  been  shown  in  section  3.13  as  a  part  of 
the  two  general  forms.  Both  are  very  similar  and  the 
choice  of  one  or  the  other  is  simply  a  matter  of  user 
preference. 

The  reporting  verbs,  together  with  the  Attr-Names 
which  follow  them  (if  any),  determine  the  format  and 
content  of  the  computer's  response  to  the  query  state- 
inert.  A  more  complete  discussion  of  the  report  format 
will  be  deferred  to  section  6.0. 

There  are  six  reporting  verbs,  LIST,  LIST- VERTICAL, 
LISTV,  COUNT,  TOTAL  and  AVERAGE,  of  which  two  (LIST- 
VEETICAL  and  LISTV)  are  identical,  differing  only  in 
spelling.  Therefore,  there  are  five  different  report 
formats  which  may  be  requested. 

Each  of  the  reporting  verbs  also  has  some  rules 
regarding  what  particle  names,  if  any,  should  appear 
with  it.  Therefore,  each  will  be  taken  in  order. 


5.31  LIST 


The  LIST  verb  requests  a  listing,  in  columns,  of 
the  data  appearing  in  the  data  fields  which  are  identified 
by  the  At  tr-Nnmes  immediately  following.  Thus,  for 
the  LIST  verb,  at  least  one  Attr-Name  must  follow,  with 
as  many  more  as  desired. 

The  data  which  aro  to  be  listed  will  come  from 
those  fields  in  the  data  base  designated  by  the  Attr-Naines 
but  only  from  those  fields  in  entries  which  qualify 
according  to  the  selection  clause.  (See  section  5.22). 

It  is  not  necessary  that  data  which  are  tested  in  the 
selection  clause  also  be  reported.  The  selection  clause 
can  test  data  in  some  fields  and  the  reporting  verb  can 
display  data  from  others.  Or  thoy  may  be  the  same  fields 
if  desired.  For  example: 

WITH  SIX  EQ  'M*  WHERE  AGE  LT  '25'  OR  AGE  GT  '65 

LIST  N/ME  AGE  ACCIDENTS  # 

The  ab<  ve  example  is  a  complete  query  statement 
(using  an  uni  amed  data  base,  but  one  that  is  assumed  to 
be  currently  active).  SEX  and  AGE  are  the  Attr-Names 
(data  fields)  being  tested  while  NAME,  AGE  and  ACCIDENTS 
are  being  reported.  Only  the  NAME,  AGE  and  ACCIDENTS 
will  be  reported  for  those  data  base  entries  which 
meet  the  requirements  of  the  selection  clause  (i.e.  for 
which  the  selection  clause  comes  out  "true’'). 

The  column  headings  of  the  report  will  be  the 
Attr-Names  (underscored),  and  the  data  from  the  respective 
fields  will  be  listed,  row-by-row,  under  the  appropriate 
column  headings. 

If  no  Attr-Name  follows  the  reporting  verb,  LIST, 
the  query  statement  will  be  rejected. 

If  there  are  so  many  Attr-Names  after  the  LIST  verb 
that  the  report  will  not:  fit  in  columns  across  the  page, 
then  the  reporting  format  will  be  switched  to  the 
LIST- VERTICAL  format,  described  in  the  next  section. 

An  example  of  the  report  for  the  above  illustration 

might  be: 

NAME  AGE  ACCIDENTS 


JOHN  SMITH  23  4 
WILLIAM  JONES  67  2 
JAMES  JOHNSON  19  3 

etc . 


5.32  LI  ST- VERTICAL  AND  LISTV 


LIST-VERTICAL  and  LISTV  are  alternate  spellings 
for  the  same  command.  The  only  difference  between  these 
and  the  LIST  verb  in  the  previous  section  is  the  format 
used  for  displaying  the  report.  Whereas  the  LIST  verb 
attempts  to  display  the  data  in  columns,  the  LIST- VERTICAL 
verb  always  displays  vertically  down  the  page. 

In  the  illustrations  in  section  5.31,  if  the  verb 
had  been  LISTV  instead  of  LIST,  the  report  example  would 
be- 


NAME 
AGE 
A CO I  DENTS 


JOHN  SMITH 

25 

4 


NAME:  WILLIAM  JONES 

AGE:  67 

ACCIDENTS:  2 


NAME:  JAMES  JOHNSON 

AGE:  19 

ACCIDENTS:  3 


etc. 


The  LIST- VERTICAL  verb  also  must  be  followed  by 
at  least  one  Attr-Name,  just  as  the  LIST  verb,  and  can 
have  ns  many  more  as  desired. 


5.33  COUNT 


The  COUNT  verb  simply  reports  a  count  of  the 
number  of  data  base  entries  which  qualify  from  the 
selection  clause  tests. 

Actually,  the  count  is  given  at  the  end  of  every 
reporl  so  that  the  COUNT  verb  is  equivalent  to  request¬ 
ing  only  that  part  of  the  report  and  nothing  more. 

The  count  will  be  shown  as  follows: 

COUNT:  37  OF  142 

where  the  first  number  is  a  report  of  how  many  entries 
quail  y  and  the  second  reports  how  many  entries  were 

tested . 


This  report  will  also  be  given  at  the  end  of  the 
reports  for  each  of  the  other  reporting  verbs.  For 
example,  in  the  LIST  report,  the  COUNT  should  correspond 
to  the  number  of  entries  which  are  listed  under  the 
headings . 

The  second  number  in  the  COUNT  report  will  always 
report  the  total  number  of  entries  in  the  data  base. 

No  Attr-Namo  follows  the  COUNT  verb,  and  if  any 
are  shown,  the  statement  would  be  rejected. 


5.34  TOTAL 


The  TOTAL  reporting  verb  is  meant  to  provide  an 
arithmetic  sum  of  the  numeric  valuos  in  the  Attr-Name 
data  fields.  Exactly  one  such  Attr-Name  should  appear 
after  the  TOTAL  verb,  and  that  Attr-Name  must  contain 
only  numeric  values  in  its  data  field. 

Note  that  the  numeric  sum  is  not  the  sum  of  all 
entries  in  that  data  field  but  rather  only  the  sum  of 
the  entries  which  qualify  according  to  the  selection 
clause.  If  there  is  no  selection  clause,  or  if  the 
selection  clause  is  written  in  such  a  way  that  every 
entry  qualifies,  then  the  sum  would  include  every 
entry . 


5.35  AVERAGE 


The  AVERAGE  verb  is  very  similar  to  the  TOTAL 
verb  except  that  the  arithmetic  sum  is  divided  by 
the  count  of  addends  before  it  is  reported. 

Since  the  COUNT  is  included  as  a  part  of  each 
of  tli  •  other  reports,  one  could  compute  the  AVERAGE 
from  the  TOTAL  report. 

The  AVERAGE  value  that  is  reported  is  the 
arithmetic  mean  of  the  values  of  those  numbers  in 
qualifying  entry  data  fields. 

Exactly  one  Attr-Name  follows  the  AVERAGE  verb. 


5.4  THE  REPORT  CLAUSE 


Tho  report  clause  consists  of  the  list  of  Attr-Names 
(attribute  names)  if  any  thnt  appear  following  the 
reporting  verb.  Each  verb  has  its  own  requirements  for 
the  number  and  type  (string  or  numeric)  of  Attr-Nnmcs 
which  may  follow  it.  These  were  discussed  in  the 
several  previous  sections  (5.3  and  following)  thnt 
described  tho  reporting  verbs.  These  requirements 
will  be  recapped  briefly  here. 

The  LIST,  LIST- VERTICAL  and  LISTV  verbs  may  be 
followed  by  one  or  more  Attr-Names  of  either  (or  mixed) 
types. 

The  COUNT  verb  has  no  Attr-Name  following  it, 
therefore  lias  no  report  clause. 

The  TOTAL  and  AVERAGE  verbs  each  have  exactly  one 
Attr-Name  following  them  in  the  report  clause,  and 
the  data  field  designated  by  that  Attr-Name  must  contain 
only  numeric  values. 

Attr-Names  in  the  report  clause  are  separated  only 
by  spaces  (one  or  more).  Any  other  separating  characters 
(commas  included)  are  illegal. 


5.5  TERMINATOR  CHARACTER 


Every  query  statement  must  be  terminated  with  a  P 
character.  Tho  function  of  the  *  termination  character 
is  to  inform  the  system  which  line  of  a  multi-line 
query  is  the  last  one,  even  if  the  entire  statement 
happens  to  fit  on  one  line. 

If  the  final  lino  of  the  query  statement  lias  been 
sent  to  the  computor  before  it  is  discovered  thnt  the  P 
character  was  left  off,  it  is  permissible  to  enter  that 
character  as  the  first  and  only  one  on  the  next  line. 
This  effectively  continues  the  line  only  for  the  purpose 
of  terminating  it. 


6.0 


REPORTING  FORMATS 


Most  of  the  reporting  format  considerations 
pertain  to  the  columnar  and  vertical  formats  of 
the  LIST  and  LISTV  verbs,  respectively.  The  remain¬ 
ing  reports  are  trivial  but  will  be  shown  for  the 
sake  of  completeness. 


6.1  NUMERIC  VALUE  REPORTS 


The  verbs,  COUNT,  TOTAL  and  AVERAGE  each  only 
report  numeric  values.  In  addition,  the  COUNT  report 
appears  at  the  end  of  each  LIST  and  LISTV  report. 

Examples  of  the  COUNT,  TOTAL  and  AVERAGE  report 
follow: 

COUNT:  228  OF  591 

TOTAL:  43149 

COUNT:  228  OF  591 

AVERAGE:  189.25 

COUNT:  228  OF  591 

The  above  examples  assumed  that  the  three  query 
statements  which  produced  them  differed  only  in  the 
verb  that  was  used  (and  no  Attr-Nome  in  the  case  of 
COUNT).  Note  therefore  that  the  AVERAGE  report  can 
bo  computer  from  the  TOTAL  report  and  conversely. 


6.2  DISPLAYING  DATA 


The  two  display  formats,  columnar  and  vertical, 
have  already  been  discussed  and  illustrated  in  sections 
5.31  and  5.32.  Additional  variations  will  only  occur 
in  (he  number  of  attributes  for  which  data  are  displayed, 
and  the  location  of  the  displayed  data  on  the  page.  This 
can  have  some  bearing  on  the  size  of  the  name  (number  of 
characters)  one  might  want  to  choose  for  a  given  kind 
of  attribute. 


6.21 


COLUMNAR  PAT A  DISPLAY 


Columnar  data  Is  displayed  by  using  the  LIST  verb, 
but  only  it'  the  dalu  columns  do  not  exceed  the  width  of 
the  display  page.  Ottierwise  the  display  will  bo  identical 
to  the  LISTV  (vertical)  display. 

One  of  the  considerations  which  will  keep  the  LIST 
display  in  columnar  format  will  bo  ttie  number  of  Attr- 
Names  in  the  display.  If  a  large  number  are  specified 
in  the  display,  there  may  not  be  enough  room  on  the 
display  page  to  list  the  data  in  columnar  format.  Two 
variables  determine  the  amount  of  column  space  needed 
for  each  Attr-Name:  1)  the  number  of  columns  in  the 
datn  field  specification,  and  2)  the  number  of  characters 
in  the  Attr-Name.  Moth  of  these  values  are  fixed  at 
the  time  the  DECLARE  statement  is  entered  for  the  Attr- 
Name  in  question.  (See  sections  4.4  and  8.5  for  more 
information  tut  the  DECLARE  statement).  The  column  space 
needed  will  be  the  larger  of  those  two  numbers  plus  the 
t wo  spaces  that  separate  the  columns. 

Thus,  if  the  user  intends  to  display  data  in 
columnar  format,  it  might  be  wise  to  attempt  to  limit 
the  number  of  characters  in  a  chosen  attribute  name  to 
no  more  (or  little  more)  than  the  number  of  columns  in 
the  data  field  being  declared.  Using  the  example  in 
section  5.21  of  a  columnar  display,  the  NAME  field  is 
apparently  determined  by  the  length  of  the  data  field 
assigned  to  it  (21  columns  in  the  example),  the  AGE 
field  might  be  three,  the  same  as  the  number  of  characters 
in  the  word,  AGE,  but  the  ACCIDENTS  field  is  certainly 
determined  by  the  size  of  the  chosen  attribute  name, 
ACCIDENTS.  ivith  only  three  columns  of  data  in  the  report, 
the  difference  is  minimal.  However,  if  seven  1  more 
At tr-Names  had  been  specified  in  the  query  statement  for 
the  report,  the  ACCIDENTS  column  might  have  made  the 
difference  between  a  columnar  or  a  vertical  report. 

By  the  same  token,  it  is  wise  not  to  include  more 
columns  in  the  data  field  than  are  needed  to  represent 
nnv  of  the  universe  of  data  which  might  appear  there. 

The  more  columns  of  data  there  are,  the  more  spread  out 
the  columnar  report  will  be. 


6.22  VERTICAL  DATA  DISPLAY 


Vertical  data  displays  result  from  the  use  of  the 
LIST-VERTICAL  and  LISTV  verbs,  and  can  result  from  the 
use  of  the  LIST  verb  if  the  display  is  too  wide  for  the 
columnar  format. 

Vertical  formats  are  organized  by  repeated  listings 
of  the  Attr-Names  down  the  left  margin,  indented  so  that 
the  colon  characters  line  up  vertically  (as  shown  in  the 
example  in  section  5.32).  The  data  are  listed  after  the 
colon.  If  the  length  of  the  data  listing  exceeds  the 
width  of  the  page,  the  remainder  of  the  entry  will  appear 
on  the  next  line.  Thus,  virtually  any  length  entry  can 
be  accomodated. 

Both  displays,  columnar  and  vertical,  include  a 
COUNT  display  after  the  last  data  line. 


7.0 


MACROS 


One  never  has  to  use  macros  to  operate  the  query 
system  but  the  use  of  macros  generally  simplifies  its 
operation.  It  is  veil  worth  the  little  extra  time 
required  to  learn  to  use  them. 

The  .Macro  feature  simply  allows  one  to  equate 
a  user-chosen  name  to  any  fixed  sequence  of  characters. 
Then,  when  that  Macro  name  is  used  in  a  query  state¬ 
ment,  the  character  string  will  be  substituted  in 
its  place  before  the  data  base  is  searched. 

The  Maci  feature  is  especially  useful  for  any 
or  all  of  the  following  applications: 

•  Abbreviation  for  character  strings  which  will 
be  repeated  in  several  query  statements  for 
the  same  data  base  (regardless  how  much  time 
separates  the  use  of  those  query  statements). 

•  Abbreviation  for  data  comparisons  (simple  or 
compound)  which  clarify  the  writing  of  the 
query  statement. 

•  Method  of  renaming  primitive  particle  names 
to  something  more  easily  remembered. 

•  Method  of  attaching  a  name  to  a  particular 
kind  of  reporting  specification  such  that 
the  same  reporting  format  can  be  easily  used 
with  several  different  selection  clauses. 

•  Abbreviation  for  the  entire  query  statement 

so  than  an  uninformed  user  can  make  that  query 
with  utmost  ease. 


7.1  DEFINING  AND  USING  MACROS 


The  DEFINE  verb  is  used  to  define  the  macro.  Its 
input  form  is: 

£FOR  Diname]]  DEFINE  Macro-Name  *  anything  # 

Notice  that  the  bracketed  portion  is  optional.  If  omit¬ 
ted,  the  currently  active  data  base  dictionary  will  be 
the  recipient  of  the  new  macro. 


The  Macro -Name  Is  made  up  the  same  way  as  any 
other  Query  system  name.  (See  naming  conventions  in 
see t ion  2.1). 


There  are  few  restrictions  regarding  the  content 
of  the  macro  character  string,  represented  by  t  tie  word, 
"anything"  above.  However,  a  few  simple  guidelines 
will  make  then  more  useful. 

Make  the  macro  a  "whole"  entity.  For  example, 
if  the  macro  is  to  contain  part  of  a  selection  clause, 
make  it  an  entire  comparison  (or  compound  comparison). 
An  example  ol  how  not  to  do  it  may  make  the  point: 

DEI  INK  ONE  SEX  EQ  # 

DEFINE  TWO  -  'M*  AND  AGE  * 

DEFINE  MR  EE  -  LT  '25'  P 

Now,  with  ttu  above  macros,  the  following  query  state¬ 
ment  could  bt  written: 

WITH  ONE  TWO  THREE  COUNT  P 

While  t  tic  above  sequence  is  valid,  the  macros  do  little 
to  help.  A  better  way  might  have  been: 

DEFINE  YOUNG-MAI.E-DR  1  VERS  -  SEX  EQ  *  M '  AND 
AGE  LT  *25’  n' 

Now  the  quor\  statement  would  be: 

W  I  TH  YOUNG-MALE- DR  I  VERS  COUNT  # 

When  using  macros  to  represent  data  comparisons 
(as  was  just  illustrated),  it  is  good  practice  to 
enclose  the  macro  string  in  parentheses  so  that  it 
will  be  treated  as  a  single  entity  regardless  where 
it  appears  within  a  selection  clause.  In  the  above 
case,  it  could  appear: 

DEFINE  YOUNG-MALE-DRIVERS  -  (SEX  EQ  ’ M’  AND 
AGE  LT  *25')  » 

In  the  above  illustrations,  the  presence  or  absence  of 
parentheses  would  have  made  no  difference.  However, 
if  macros  had  been  used  to  construct  the  selection 
clause  shown  toward  the  end  of  section  5.25,  the  use 
of  parentheses  could  be  very  important.  When  the  data 
comparisons  iti  the  macro  definitions  are  complete,  the 
parentheses  are  advisable. 


Use  macros  in  defining  other  macros ,  espec i a 1 ly 
when  complex  query  statements  are  necessary.  For 
example,  consider  the  simplicity  and  clarity  of  the 
query  statement  below  after  the  macros  have  been 
def ined: 

DEFINE  JAPAN  -  (MAKE  El}  'TOYOTA'  '  DATSUN ' 

'HONDA'  'MAZDA')  t* 

DEFINE  GERMAN  -  (MAKE  EQ  ' VW '  'BMW'  'MERCEDES')  * 

DEFINE  ITALIAN  -  (MAKE  El}  'FIAT')  W 

DEFINE  BRITISH  (MAKE  El}  'ROLLS'  'JAGUAR' 

'TRIUMPH')  » 

DEFINE  t BENCH  (MAKE  KQ  'RENAULT')  ft 

DEFINE  FOKIEGN  •  (JAPAN  OR  GERMAN  OR  ITALIAN  OR 
BRITISH  OR  FRENCH)  * 

DEFINE  GOOD-MILEAGE  -  (MPG  GE  '35')  # 

DEFINE  FAIR-MILEAGE  -  (MPG  GE  '20'  AND  MPG  LT  '35')  ft 

DEFINE  POOR-MILEAGE  -  (MPG  LT  '20')  ft 

Now,  let's  look  at  the  lists  of  foriogn  cars  in  each  of 
the  three  mileage  categories: 

LIST  MAKE  WHEN  FURIEGN  AND  GOOD-MILEAGE  # 

LIST  MAKE  WHEN  FORI  EG N  AND  FAIR-MILEAGE  * 

LIST  MAKE  WHEN  PORIEGN  AND  POOR-MILEAGE  ft 

Or,  there  would  be  many  other  alternatives,  such  ns: 

LIST  MAKE  MPG  WHEN  PORIEGN  ft 

LIST  MAKE  MPG  WHEN  NOT(FORIEGN)  AND  GOOD-MILEAGE  ft 

LIST  MAKE  MPG  WHEN  (BRITISH  OR  GERMAN)  AND 
(GOOD- MILE  AGE  OR  FAIR- MILEAGE)  ft 

(Please  forgive  the  omission  of  any  favorite  foriegn 
car  makes). 


8.0 


COMMAND  VERBS 


Command  verbs  are:  PRESTORE,  READ-CARDS, 
DATA-BASE,  DEFINE  and  DECLARE.  All  except  PRESTORE 
have  been  discussed  at  some  length  in  earlier  sections. 
The  discussion  in  this  section  will  be  brief,  giving 
the  general  forms  for  each. 


8.1  PRESTORING  A  CARD  DECK 


The  general  form  for  the  PRESTORE  verb  is: 

PRESTO RE  Filename  [n]  * 

The  PRESTORE  verb  is  used  to  load  a  card  deck  into 
the  Query  system,  making  it  available  one  time  only  to 
any  user  who  accesses  it  by  using  the  READ-CARDS  verb 
with  the  same  Filename.  Only  the  system  operator  is 
allowed  to  use  the  PRESTORE  verb  since  the  use  of  this 
verb  must  be  coordinated  with  the  placement  of  the 
card  deck  in  the  reader  device. 

No  interpretation  of  the  cards  whatever  will  be 
done  during  the  prestore  operation.  The  last  card 
belonging  to  the  named  Filename  must  contain  dollar 
signs  ($S)  in  the  first  two  columns  which  signal  the 
end  of  that  deck.  The  $$  card  will  not  be  a  part  of 
the  Filename  reference,  and  will  have  no  further 
function . 

The  purpose  of  the  PRESTORE  verb  is  to  keep  the 
operator  in  control  of  the  actual  card  reader,  turning 
the  file  over  to  the  user  who  requested  the  prestore 
when  the  operation  is  finished.  The  prestore  operation 
uses  otherwise  idle  system  time  to  perform  its  work. 

The  ”n"  parameter  is  optional.  When  omitted, 

"n"  is  understood  to  have  the  value,  80  (n=80),  the 
number  of  columns  on  the  card.  Acceptable  values  for 
the  "n”  parameter  are  between  one  and  80,  designating 
the  last  column  on  the  card  from  which  data  are  to  be 
taken.  Card  columns  beyond  that  number  will  be  regard¬ 
ed  as  though  they  were  blank.  This  permits  the  user 
to  drop  off  such  things  as  sequence  numbers  from  the 
cards.  For  example: 


PRKSTORE  NEW- DECK  72  # 


In  this  example,  Filename  NEW-DECK  would  contain  a  copy 
of  the  card  deck  just  read  but  with  the  last  eight  columns 
blanked  out. 


8.2  USING  A  PRESTORED  CARD  DECK 


The  user  inputs  to  the  Query  system  from  card 
deck  via  a  two-step  operation.  He  first  asks  the 
operator  to  prestore  the  deck  into  a  given  Filename 
and  also  specifies  the  last  data  column  (if  less  than 
the  full  card).  The  operator  prestores  the  deck 
using  the  PRESTORE  verb.  (See  section  8.1). 

The  user  will  be  able  to  tell  from  the  system 
messages  when  the  deck  is  ready.  If  the  prestore 
has  not  yet  been  initiated,  the  message,  "PRESTORE 
FILE  NAME  IS  NOT  ON  DISK.”  If  it  is  in  progress, 
the  message  will  be,  "PRESTORE  FILE  IS  NOT  READY  YET." 

The  prestored  file  is  accessed  by  the  READ-CARDS 
verb.  Its  general  form  is: 

[FOR  Diname]  READ-CARDS  Filename  [n]  # 

The  brackets  denote  optional  entries,  as  before. 

The  cards  that  are  read  using  this  command  verb 
will  appear  to  be  coming  directly  from  the  card  reader, 
except  much  faster.  Since  the  input  format  is  generally 
the  same  for  cards  and  for  the  terminal,  the  card  deck 
represents  a  convenient  method  for  stacking  a  large 
number  of  terminal  inputs  for  efficient  entry  into  the 
Query  system.  The  most  likely  card  entries  will  be  the 
dal  a  base  entries  and  the  DEFINE  and  DECLARE  statements. 
Together,  these  will  comprise  the  entire  data  base  and 
its  dictionary.  After  the  last  card  has  been  read, 
entry  will  switch  back  to  the  terminal. 

If  an  error  is  encountered  in  reading  the  card 
deck,  the  error  will  be  reported  at  the  terminal  and 
the  remainder  of  the  card  deck  will  bo  discarded.  It 
will  then  be  the  responsibility  of  the  user  to  repunch 
the  offending  card  and  prestore  again  that  card  and  the 
remaining  ones.  Using  the  READ-CARDS  verb  again  with 
the  Dlname  option,  the  balance  of  the  card  deck  will  be 
added  to  the  data  base. 
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Th  ;  "n"  optional  parameter  in  the  READ-CARDS 
general  form  is  similar  in  interpretation  to  the 
one  in  the  PRESTORE  verb  form.  (See  section  8.1). 
However,  instead  of  regarding  the  columns  past  "n" 
as  being  blanks,  it  instead  regards  the  cards  as 
being  only  *’n"  columns  long.  The  difference  is 
only  pertinent  while  in  the  data  base  entry  mode. 

(See  section  3.2).  Instead  of  the  data  entry  being 
80  characters  per  card  segment,  it  will  be  taken  as 
"n"  characters  per  card  segment.  Thus,  if  n=20  and 
there  were  10  cards  per  data  base  entry  (i.e.  the 
#  character  terminates  each  tenth  card) ,  then  the  20 
columns  in  the  sixth  card  would  be  columns  101-120 
in  the  data  base  entry,  whereas  they  would  be  columns 
401-420  if  n=80.  The  user  might  find  that  50-column 
cards  (n=  50)  would  make  it  easier  to  format  the  data 
base  entries. 

Section  4.3  shows  another  example  of  the  use 
of  the  READ-CARDS  verb. 

After  the  READ-CARDS  verb  has  been  transmitted 
and  after  its  execution  completes,  the  "Filename" 
will  no  longer  exist  in  the  Query  system,  and  that 
name  can  then  be  used  for  something  else. 


8.3  CREATING  OR  EXTENDING  A  DATA  BASE 


The  use  of  the  DATA-BASE  command  verb  was  dis¬ 
cussed  extensively  in  sections  4.0  through  4.3.  Its 
general  form  is: 

DATA-BASE  [Dlnarne]  # 

The  next  input  will  be  processed  as  an  entry  to  the 
data  base. 

If  the  Dlname  is  given,  then  the  associated 
data  base  will  be  extended  by  the  next  entries  (if 
the  data  base  by  that  name  already  existed) ,  or  a 
data  base  by  that  name  will  be  created  if  the  name  is 
new.  If  the  name  does  already  exist  and  the  input  is 
from  the  terminal,  then  the  user  will  be  asked  to 
confirm  that  the  intention  is  to  add  to  this  data  base. 

If  the  Dlname  is  omitted,  the  currently  active 
data  base  will  be  assumed,  or  an  error  will  be  reported 
if  none  is  currently  active. 
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8.4  DKF1N  1  N A  MACHO  NAME 


The  general  form  for  the  DEFINE  verb  is: 

[FOR  Dinamo]  DEFINE  Macro-Name  -  anything  ft 

The  DEFINE  verb  has  been  discussed  in  detail 
in  sections  7.0  and  7.1. 

Note  that  defined  macros  become  a  permanent 
part  of  tho  data  base  dictionary  and  remain  avail¬ 
able  whenever  that  data  base  is  used. 


H..>  PEc'l.AK  |  V>  ATTU IIU’TE  NAMES 

Attribute  names  are  used  to  identity  da  t  a  fields 
within  the  data  base  when  composing  a  query  statement. 
The  data  fields  may  either  be  arbitrary  strings  of 
characters  or  numeric.  The  general  form  for  either 
declaration  varies  only  with  the  mnemonics  SIR  (string) 
and  NUM  (numeric): 

[FOR  Dinamo]  DECLARE  Attr-Nnme  STR(cl,c2)  ft 

[FOR  Din  amt']  DECLARE  Attr-Nnme  NUM(cl,c2)  ft 

The  ot  and  c2  parameters  refer  to  the  beginning  column 
number  amt  ending  column  number,  respectively,  of  the 
designated  data  field. 

If  the  second  form  is  used  (numeric  declaration), 
t  lie  designated  data  field  must  only  contain  a  numeric 
value,  optionally  including  a  decimal  point  and.  or 
an  arithmetic  sign. 

Note  that  declared  attribute  names  become  a 
permanent  part  of  the  data  base  dictionary  and  remain 
nvallible  whenever  that  data  base  is  used. 
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CONTROL  STATEMENTS 


Control  statements  begin  with  a  control  character 
($)  in  column  one  of  the  input  and  have  no  termination 
character.  (See  section  3.3). 

The  typical  user  needs  only  one  control  state¬ 
ment,  $OUT,  that  signs  that  user  off  from  the  system. 
The  remaining  control  statements  are  used  only  by 
the  system  operator. 


).  1  USER  SI  INOKF,  $OUT 


When  any  user  wishes  to  sign  off  from  the  Query 
system,  the  control  statement,  $OUT,  is  input.  The 
user  may  sign  off  at  any  time  and  resume  again  with 
the  previous  work  at  the  next  login. 


‘>.2  OPERATOR  CONTROLS 


•  $AI)PLOG  /userid/userid/usorid/otc. 

This  statement  adds  authorized  login  identities 
to  the  list. 

•  $  DEI,  LOG  /userid/userid/usorid/otc. 

This  statement  removes  user  identities  from 
the  authorized  login  list. 

•  $DATE"mmddyy 

This  statement  permits  the  operator  to  set  the 
current  date  as  six  digits,  two  each  for  the 
month,  day  and  year.  In  most  cases,  this  will 
not  be  necessary  ns  it  will  have  been  set  auto¬ 
mat!  eally . 

•  $AU>  n 

This  state  permits  the  operator  to  assign 
auxiliary  operator  status  to  any  terminal 
numl  ei*  "n".  This  status  is  limited  to  only 
one  terminal  at  a  time.  Its  main  use  is 
for  remote  maintenance  of  the  system. 


•  $QUIT  ALL 

This  control  statement  halts  the  execution 
of  the  Query  system  after  logging  off  any 
active  users. 

•  Full  interactive  debugging  is  available  to 
the  operator  which  uses  the  same  statement 
syntax  as  the  PLANIT  system  (but  with  the 
addition  of  the  $  prefix).  Since  this  feature 
has  very  limited  application  among  the  user 
community,  it  is  not  described  in  more  detail 
here. 


10.0  OPERATING  PROCEDURES 


The  operation  of  the  Query  system  is  extremely 
simple.  There  is  nothing  to  load,  nothing  to  save 
and  no  operations  which  must  complete  prior  to 
sign  off.  Each  operation  is  complete  in  a  single-  or 
multi-line  entry.  Although  at  first  it  may  appear 
that  the  loading  of  a  card  deck  is  similar  to  loading 
a  program,  a  simple  examination  of  the  deck  shows  it 
to  be  only  a  batch  of  terminal  inputs  which  have  been 
preoared  ahead  of  time  for  rapid  entry. 

There  are  a  few  items  of  information  which  will 
help  in  using  the  system. 


10.1  SICNING  ONTO  THE  SYSTEM 


After  connecting  the  terminal  to  the  Query 
system  (by  dialing  or  whatever),  the  user  will  respond 
o  the  message: 


PLEASE  LOG  IN 

Th«>  login  name  must  have  previously  boon  put  into  the 
authorized  login  list.  The  operator  can  do  this. 


10  2  TERMINAL  PROMPTS 


There  are  three  terminal  prompts,  corresponding 
to  the  three  possible  kinds  of  entries  which  might  be 
expected.  They  are  the  following: 

DMS^  This  abbreviation  for  Data  Management 
System  indicates  that  the  user  can 
s tart  any  query  statement  or  control 
statement  on  this  line. 

y  This  indicates  that  the  computer  is  expecting 
the  continuation  of  a  query  statement  which 
was  started  on  a  previous  line. 
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1^  This  prompt  Indicates  that  the  Query 

system  is  expecting  datn  to  be  added  to 
a  data  base.  The  number  indicates  the 
column  number  of  the  entry.  Thus,  the  "1" 
indicates  a  new  entry,  and  continuation 
lines  will  have  correspondingly  larger 
column  numbers  in  the  prompt.  When  the  $ 
character  has  terminated  the  entry,  the 
noxt  column  number  prompt  will  again  be  "1." 


10.3  LINE  ECHOING 


Query  statements  will  be  repeated  for  the  user. 

Tht  echo  of  .he  statement  will  normally  occur  after 
tht  #  terminator  character  has  been  typed  and  entered. 
However,  a  partial  echo  will  occur  sooner  in  the  event 
of  an  error.  This  will  be  discussed  more  fully  in  the 
next  section. 

In  addition  to  assisting  in  error  detection,  the 
echoed  statement  shows  the  user  exactly  what  search 
format  will  bo  used.  Actually,  it  is  not  an  echo,  but 
a  l econstituted  line.  If  the  Dlname  has  been  omitted 
f rt m  the  statement,  it  will  appear  in  the  echo.  If 
mat ros  are  used,  the  substitutions  will  appear  in  the 
echo.  Therefore,  the  echo  can  be  much  longer  than  the 
typed  query  statement.  The  echo  will  show  exactly 
what  the  statement  would  look  like  after  default  condi¬ 
tions  have  been  supplied  and  macros  have  been  eliminated. 

The  echoed  line  will  be  most  useful  in  the  event 
that  the  user  suspects  that  the  desired  data  are  not 
being  found  for  the  report,  to  provide  additional 
in'ormation  for  correcting  the  query  statement. 


10  4  ERROR  MESSAGES 


Error  diagnostic  messages  will  appear  at  the 
terminal  in  the  event  that  the  statement  will  not 
execute.  In  addition,  if  the  error  has  been  discovered 
in  the  syntax  of  the  query  statement,  the  echoed  line 
wfi' l  end  at  the  point  the  error  was  discovered.  The 
user  will  have  both  the  error  message  and  the  position 
indication  of  the  error. 
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The  user  should  follow  local  conventions  for  single 
character  corrections  (rubout  or  backspace)  and  single 
line  corrections  (lint*  cancellation). 

In  addition,  an  entire  multi-line  query  statement 
may  be  cancelled  by  entering  a  blank  line  (only  the 
carriage  return  key)  in  plnce  of  the  next  continuation 
line.  The  next  prompt  will  bo: 

DMS> 

Note  however  that  the  result  would  be  different  if  the 
blank  line  should  be  entered  while  building  a  data  base. 
In  that  case,  a  number  of  blanks  would  be  entered  into 
the  data  base  line  which  is  equal  to  the  columns  on  the 
tormina l . 

Also,  in  this  regard,  should  an  error  be  discovered 
by  the  PQS  syntax  check,  it  will  be  reported  at  the  time 
the  offending  line  is  entered.  Thus,  if  the  query  state¬ 
ment  is  to  extend  over  several  lines,  the  error  will  be 
reported  when  tt  is  made,  not  when  the  query  statement 
is  complete.  Following  the  report  of  the  error,  the 
entire  query  statement  must  be  re-typed. 


10.(5  MODE  SWITCHING 


There  are  three  basic  modes  of  operation: 

•  Query  mode 

•  Data  base  creation  mode 

•  Control  statement  mode 

The  Query  mode  will  be  prompted  by  the  !,DMSV'  characters. 

To  change  from  the  Query  mod  to  the  Data  base  creation 
mode,  the  DATA-BASE  command  is  used.  The  data  base  col¬ 
umn  number  prompt  will  remind  the  user  of  that  mode.  To 
revert  back  to  the  Query  mode,  the  character  is  entered 

as  (tie  only  iharacter  on  the  line.  (It  may  have  to  be  done 
twice  if  the  first  one  is  used  to  terminate  a  data  base  line 
in  progress).  The  Control  statement  mode  is  entered  via  the 
initial  "$"  character  and  always  reverts  automatically  to 
the  Query  mole  again. 
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SIGNING  OFF  FROM  THE  SYSTEM 


To  sign  off  from  the  system,  the  user  types: 

$0UT 

Note,  however,  that  this  is  a  Control  Statement  format 
so  it  can  only  be  entered  while  in  the  Query  Statement 
mode.  In  case  the  user  is  in  the  Data  Base  Creation 
mode  at  the  time  the  "$0UT"  command  is  desired,  the 
mode  must  first  be  switched.  This  can  be  done  by 
entering  a  "ff"  character  alone  on  the  line.  If  a 
data  base  line  was  in  progress,  this  will  result  in 
a  ”  !>’’  pror.pt,  and  a  second  line  will  need  to 

b<  input. 

When  the  "DMSC>"  prompt  is  seen,  the  user  can 
enter  the  "$0UT"  control  statement.  (See  also 
Section  10.6  for  mode  switching). 
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I  NS TALL AT 10  N  IN  FORMATION 


Installation  of  the  Portable  Query  System  is 
nearly  identical  to  that  for  PLANIT  (Programming 
LANguage  for  Interactive  Teaching),  a  computer- 
assisted  instructional  time-sharing  system  which  is 
also  portable.  Since  installation  documentation 
already  exists  for  PLANIT,  this  discussion  will  be 
limited  to  differences  in  the  installation  of  the 
PQS  from  PLANIT. 


DIFFERENT  I NSTALLATION  PARAMETER  NAMES 

There  are  seven  parameter  names  in  the  PQS  listing 
which  either  arc  not  found  in  PLANIT  or  appear  with 
a  different  meaning:  CONTOUR,  DIGITS,  NUMRECS,  CHKPRKP, 
ENTRYSIZE,  DICTSIZE  and  WORKSPACE.  There  are  several 
parameter  names  which  appear  in  PLANIT  which  do  not 
'  pear  in  PQS  that  should  be  disregarded.  The  above 
ven  names  have  comments  in  the  listing  which  attempt 
to  explain  the  purpose  of  the  parameter  names.  This 
discussio  will  give  a  little  more  detail  for  each. 


CO  NT  C  MR 

This  parameter  simply  selects  the  character 
which  will  be  used  as  the  Control  Statement  prefix 
character.  The  value  chosen  must  be  one  from  the 
list  of  characters  in  the  character  set  listing  follow¬ 
ing  the  parameter  listing.  Thus,  the  number  for  the 
dollar  sign  ($)  character  is  55.  This  can  be  changed 
to  another  character  so  long  as  it  is  not  a  letter  or 
a  digit  and  is  not  used  for  other  purposes  in  tho  lan¬ 
guage. 


DIGITS 


This  parameter  allocates  space  for  numbers 
i<:so(-1ntrd  w  th  the  primitive  particle  names,  GREATEST, 
SMALLEST.  NEAREST,  TOTAL  and  AVERAGE.  The  number  of 
digits  chosen  should  be  the  sum  of  the  digits  to  the 
left  of  'he  decimal  point  plus  the  digits  to  its  right. 

For  example,  if  it  is  desirable  to  provide  space  for 
a  number  whose  maximum  size  will  be  10^  carried  out 
to  four  decim.nl  places,  the  value  foi'  DIGITS  should  bo  10. 


Although  NUMRECS  has  the  same  interpretation  as 
in  PLANIT,  the  cons i derat  ions  which  go  into  choosing 
a  value  will  be  somewhat  different.  A  paragraph  below 
will  discuss  the  disk  files  for  PtJS  and  will  suggest 
an  appropriate  allocation  of  records  for  each  file. 

The  NUMRECS  parameter  value  should  be  the  sum  of  those 
numbers  of  records  (or  larger  to  allow  for  growth). 


CHKPRKP 

In  the  two  general  forms  of  the  query  statement, 
the  document  presents  a  distinction  in  the  placement 
of  t he  prepositions,  WITH,  WHERE  and  WHEN.  However, 
t he  system  will  work  equally  well  if  no  distinction 
is  enforced.  A  value  of  ”0"  for  this  parameter  will 
drop  any  distinction  between  these  three  preposition 
names . 


ENTRYSIZE 

This  parameter  will  determine  the  size  of  the 
da  a  buffers  for  the  data  base,  and  in  so  doing,  will 
limit  the  size  of  any  one  entry  in  a  data  base.  The 
value  chosen  for  this  parameter  is  not  necessarily 
related  to  efficiency  since  multiple  entries  will  be 
packed  into  single  buffers  when  sizes  permit.  In  fact, 
it  would  be  more  desirable  to  have  large  buffers  with 
several  entries  per  buffer  than  to  have  small  ones 
since  it  would  tend  to  reduce  the  number  of  disk  accesses 
in  searches  of  the  data  base.  The  resulting  buffer  size 
will  be  slightly  larger  than  the  ENTRYSIZE  divided  by 
the  number  of  bytes  in  a  computer  word.  Therefore, 
values  in  the  range  of  1000  to  5000  should  be  appropriate. 


PUTS  17  F, 

This  parameter  represents  an  approximation  of 
the  number  of  particle  names  which  can  be  added  to  the 
data  base  dictionary,  including  all  associated  with  the 
DECLARE  (Attribute  Names)  and  DEFINE  (Macros)  verbs. 
Since  the  length  of  the  macros  are  indeterminate,  the 
number  will  not  be  exact.  The  effect  of  large  values 
for  tills  parameter  will  show  in  sizes  for  File  number 
two.  Values  in  t he  range  of  25  to  100  should  normally 
be  sufficient. 
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WORKSPACE. 

This  parameter  is  possibly  the  most  difficult  to 
assess.  It  determines  the  amount  of  space  to  be  avail¬ 
able  for  "parsing"  a  query  statement  into  its  component 
parts,  to  be  ready  for  the  data  base  search.  The 
component  parts  include  particle  names  (one  entry  each) 
and  other  (nor-name)  characters  (one  entry  each).  The 
query  statemert  to  be  parsed  includes  the  concatenation 
of  all  continied  lines  up  to  the  termination  character, 
expanded  by  tie  substitution  of  all  Macro  texts. 

The  value  chosen  for  this  parameter  will  limit 
the  length  (and  complexity)  of  the  query  statements  which 
might  be  composed.  A  value  of  300  would  seem  to  be 
sufficiently  generous. 


The  remaining  parameter  names  are  no  different 
than  in  PLAN IT. 

[TSK  FILKS 


The  PQS  uses  the  same  disk  file  numbering  system 
as  PLANIT.  using  the  same  file  numbers  for  the  same 
purposes  t  >  the  extent  possible.  Whereas  PLANIT 
ormally  uses  10  (or  11)  disk  files,  PQS  uses  eight. 
The  chart  below  shows  the  files  and  suggests  an  appro¬ 
priate  number  of  records  to  allocate  for  each.  The 
discussion  which  follows  the  chart  comments  on  file 
sizes.  The  "Activity  index"  column  cn  the  chart  is 
meant  to  suggest  the  relative  frequency  of  use  in  case 
there  is  an  optimum  choice  of  placement  on  disk. 


File  Number  Identification  No.  Records  Activity 


1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 


Table  of  Contents 
Data  Base  Dict¬ 
ionary 
Not  used 

Data  Base  Entries 
Not  used 
User  Swaps 

Not  used 
Snapshot  for 
error  recovery 
Core  Initializa¬ 
tion 

Prestored  decks 
Messages 


2-3  4 

1/Data  Base  5 
0 

500  plus  1 

0 

1/Active  2 

user 

0 

1  8 

2  7 

100  plus  6 
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Index 


Files  one  and  four  have  the  same  size  records, 
tht  size  being  determined  by  the  ENTRYSIZE  parameter. 

The  record  size  of  File  two  is  set  from  the 
DU  TSIZE  parameter. 

Files  six  and  nine  contain  the  "user  swap"  portion 
of  the  Common  data,  beginning  with  the  "NTOP"  item  name 
and  continuing  through  the  end. 

File  eight  is  small,  mainly  containing  the  "IDISK" 
array  and  the  "LOGNR"  array  entries. 

Files  10  and  11  have  the  same  size  records,  being 
set  from  the  SPOOLSZK  parameter.  Since  cards  are  handled 
in  "batches",  SI’OOLSZE  sets  the  size  of  those  batches. 
Thus,  SPOOLSZE  multiplied  by  the  number  of  records  in 
File  10  will  determine  the  largest  single  deck  (or  collec¬ 
tion  of  smaller  decks)  which  may  be  prestored  prior  to 
being  used.  The  MSGBUG  array  will  contain  the  data  which 
are  used  with  Files  10  and  11. 


MIOP  INTERFACE 

The  MIOP  interface  codes  are  identical  to  those 
for  PLANIT.  However,  there  are  several  operations 
which  will  not  be  used  at  the  present  time,  including: 

•  Card  punch 

•  Line  printer 

•  Tape  read  and  write 

•  Timed  terminal  read 

It  is  entirely  proper  to  use  the  same  MIOP, 
LDl'YTE  and  SBYTE  routines  for  PQS  as  for  PLANIT  even 
though  some  of  the  operations  will  not  be  exercised. 
Hoy  ever,  the  disk  files  attached  to  the  PQS  MIOP 
should  not  be  the  same  as  those  attached  to  the 
PL/.NIT  MIOP  if  either  are  to  be  preserved. 
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INITIALIZATION  DECK 


The  Initialization  Dock  for  PQS  In  similar  to 
(and  servos  the  same  function  as)  the  Cardsfile  deck 
m  IM  AM  r.  Of  course  the  messages  and  initialization 
data  are  different,  but  the  same  purposes  are  served. 

Among  those  data  which  should  be  of  concern  to 
the  operator  in  the  Initialization  Deck  are  the 
fol l owing : 

•  "C”,  "W",  "H"  or  "F"  as  the  first  character 
of  the  first  card  to  designate  Cold,  Warm, 

Mot  or  Forced  starts,  respectively.  The 
remainder  of  that  card  should  remain  un¬ 
changed  once  the  final  character  9ot  is 
established.  The  four  starts  are  the  same 

as  in  PI.AN1T,  with  the  Cold  start  to  initially 
start  the  system,  the  Warm  start  to  restart 
the  system  only  with  data  changes,  the  Hot 
start  for  usual  restarting,  and  the  Forced 
start  as  a  very  last  resort  solution  in  case 
the  Warm  and  Hot  starts  repeatedly  fail. 

•  The  1FBTN  card  must  contain  numbers  chosen 
for  the  records  allocated  in  each  file, 
including  zeros  for  those  files  where  no 
records  are  needed  (Files  3,  5  and  7). 

•  Operator  terminal  number. 

•  Quantum  size  (about  one  second  is  average). 

•  Login  identities. 

I iv  the  case  of  a  "Hot"  start,  only  the  first  card 
will  be  read,  thus  only  that  card  needs  to  be  used.  The 
remaining  start  types  use  the  entire  deck. 
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ABSTRACT 


This  pa]  or  describes  the  CONVERT  program.  CONVERT  is 
designed  to  i onvet  t  PI.ANIT  Student  Record  data  into  punched 
card  format  such  that  it  can  easily  be  input  to  a  data 
management  s  stem,  particularly  the  On-Line  Query  System. 

This  enables  PI.ANIT  authors  to  analyze  responses  the  students 
have  given  to  their  prepared  lesson  scenarios. 

By  running  CONVERT  repeatedly,  using  different  PLAN1T 
data  flies  each  time,  the  results  of  records  pertaining  to 
several  PI  .AN  I T  lessons  can  be  converted  into  a  large  single 
data  base,  suitable  for  scanning  with  Query  statements. 

CONVERT  must  run  on  the  same  computer  used  by  PLANIT  to 
create  the  Student  Record  files,  but  the  punched  card  output 
from  CONVERT  could  be  used  on  any  machine. 

This  document  also  discusses  the  installation  and 
operation  of  the  CONVERT  program. 
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i  introduction 

CONVERT  is  a  batch  computer  program  which  is  designed  to  be  used 
in  conjunction  with  two  time-sharing  systems,  PI.AN1T  and  the  On-Line 
Query  System.  It  is  necessary  to  assume  that  the  reader  has  some  familiarity 
with  both  of  these  time-sharing  systems  in  order  to  explain  the  function 
of  the  CONVERT  program.  Roth  systems  operate  independently  and  information 
about  them  can  be  obtained  from  their  operation  manuals.  The  PLAN IT 
\uthor's  Cnide,  T>!- (L) —4422/ 00 l / 0 1 ,  and  the  Query  System  Manual.  It  is 
easiest  to  begin  describing  CONVERT  with  some  preliminary  information  about 
tlu  si  neighboring  time-sharing  systems. 

The  On-Line  Query  System  is  designed  to  scan  a  data  base  of  a  pre- 
sp  eltied  format  and  select  those  records  which  correspond  to  specific 
data  values.  The  operator  can  set  the  data  values  in  a  form  sentence 
which  includes  logical  connectives,  (AND,  OR,  NOT).  This  sentence 
i-,  called  a  query  statement  and  can  be  used  to  direct  a  search  for  those 
records  which  correspond  to  the  data  values  which  were  specified  in  the 
statement.  The  data  base  must  be  arranged  as  a  sot  of  data  records,  all 
of  uniform  format  and  a  set  of  system  statements  which  name  the  data  base 
and  specify  the  fields  for  each  variable  on  the  data  records.  The  form 
for  a  data  base  is  discussed  in  more  detail  in  section  11  of  this  paper. 

PI.ANIT  is  also  a  tine-sharing  system,  but  it  serves  an  entirely 
different  purpose  than  the  Query  System.  In  author  mode,  PLANIT  provides 
its  ser';  with  all  of  the  tools  which  are  necessary  to  write  a  lesson 
which  can  later  be  used  for  interactive  on-line  teaching.  The  PLANIT 


lessons  consist  of  an  ordered  sequence  of  questions  and  decision  points 
which  are  called  frunes.  When  a  student  executes  a  PLANIT  lesson, 

(execute  mode),  he  i ypes  answers  to  the  sequence  of  questions  as  they 
appear  on  the  computer  terminal.  Depending  on  his  responses,  the  student 
may  he  branched  to  other  frames  in  the  lesson  or  to  other  lessons  in  order 
to  adjust  the  instructional  material  to  his  rate  of  learning.  All  of  the 
questions  ad  the  h  .inchin;  options  must  he  initially  constructed  as  frames 
in  ri  \NI r  b>  the  le  .•  u  author.  As  a  student  executes  a  lesson,  a  record 
of  his  performance  s  automatically  stored  onto  a  disk  file  called  the 
STUDENT  RECORDS  fib-.  1  he  data  entries  which  are  kept  on  the  STUDENT  RECORDS 
file  are  listed  in  section  II  of  this  document. 

One  major  reason  for  keeping,  records  of  students'  performance  is  to 
provide  the  author  with  a  means  for  judging  the  effectiveness  of  the  lesson. 

An  author  C3n  view  these  records  at  his  terminal,  one  student's  record  at 
a  time,  and  determine  how  well  each  question  fits  into  the  programmed  instruction 
sequence.  For  example,  if  a  question  frame  in  a  lesson  does  not  convey  any 
new  text  material  and  all  of  the  students  are  answering  it  incorrectly,  the 
au'hor  may  want  to  remove  it  from  the  lesson  or  change  it  into  a  more  useful 
en'ry  for  teaching.  To  print  out  a  student's  performance  record  the  author 
mu  ;t  first  put  the  record  into  computer  memory  using  the  'GET'  and  'ATTACH' 
co  \mands  in  Pl.ANIT.  Then  to  print  the  record  the  author  can  use  the  'DISPLAY* 
co  mand .  For  more  detail  on  the  use  of  these  commands  see  the  Pl.ANIT  Author's 
C.u  de,  page  111-35.  The  ability  to  scan  these  performance  records  for  specific 
it  ms  can  be  very  valuable  to  an  author.  After  noting  this  value  it  should 
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become  evident  that  a  program  which  converts  PLANIT  student  records  into 
data  l  ase  form  suitable  for  Query  System  processing  would  be  extremely 
useful .  The  CONVERT  program  is  designed  to  perform  this  task.  In  relation 
to  the  discussion  above,  the  description  of  the  CONVERT  program  can  proceed. 

CONVERT  is  a  batch  program  that  converts  a  PLANIT  STUDENT  RECORDS  file 
from  the  PLANIT  time-sharing  system  into  a  data  base  which  is  suitable 
lor  use  in  the  Quer’  time-sharing  system.  Each  record  of  the  data  base 
which  is  produced  will  correspond  to  a  student's  response  to  a  particular 
frame  in  the  PLANIT  lesson.  CONVERT  works  on  the  tape  format  of  the  PLANIT 
tude  it  records  to  produce  a  data  base.  The  tape  format  of  the  PLANIT 
tude  it  records  is  obtained  by  entering  the  command  'UNLOAD'  in  PLANIT.  For 
eta  's  of  the  UNLOAD  command  refer  to  the  PLANIT  Language  Reference  Manual, 
page  /I— 11.  The  tape  format  form  of  the  student  records  does  not  imply  that 
tley  are  necessarily  stored  on  tape.  They  might  be  stored  on  disk  depending 
upon  how  PLANIT  was  installed  on  the  given  target  machine.  CONVERT  runs 
a  batch  job  with  one  run  for  each  UNLOADed  STUDENT  RECORDS  file.  The 
ULLOADed  file  consists  of  all  the  records,  (one  record  per  student),  which 
were  produced  from  the  execution  of  one  PLANIT  lesson.  Convert  will  produce 
a  data  base  each  tine  it  is  run.  Each  data  base  corresponds  to  a  PLANIT  lesson. 

The  Query  system  provides  for  the  combining  of  several  data  bases  ir.to  one 
! • rge  data  base.  This  enables  the  operator  to  scan  data  which  spans  the 

nge  of  several  PL.iNIT  lessons.  For  additional  information  on  concatenating 
d; ta  bases  see  sect  .on  III.  When  converted  into  data  base  form  the 
forma'  of  each  record  of  student  performance  data  is  uniform  and  all  of  the 
additional  statemen  s  which  are  necessary  to  complete  the  data  base  are 
aided  by  the  CONVERT  program.  CONVERT's  output  file  can  be  used  directly 
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.»s  input  to  the  Query  System.  In  most  oases,  PI.AN1T,  CONVERT,  and  the  On-Line 
Query  System  will  be  used  on  the  same  computer.  In  fact,  this  is  required 
tor  PLANIT  and  CONVERT.  't  is  possible  to  take  a  CONVERT  data  base  which 
was  produced  on  one  machine  and  process  it  on  another  machine  us  ins  t  Ire*  Query 
System.  This  capability  makes  it  possible  to  carry  out  the  sequence  of  events 
which  are  need  d  to  analyze  student  per  ornunce  data  even  though  PLANIT  and 
the  Query  System  may  no:  be  available  on  the  same  machine. 

In  summary,  th  CO  .VI  Kl'  ,  .  gram  en  ihles  PIJVNIT  authors,  using  the  Query 
System.,  to  analv/e  the  responses  to  specific  questions  in  a  lesson.  Each  of 
the  variables  in  the  output  format  can  be  used  as  selection  criteria  within 
the  Query  fysten.  More  than  one  PI.ANIT  lesson  can  be  converted  into  data  base 
form  bv  ruining  CONVERT  several  times.  Each  of  the  outputs  which  are 
produced  b>  multiple  runs  can  he  prestored  as  a  single  data  base  in  the 
Query  Syst«m.  Coordination  of  the  operation  of  PLANIT,  CONVERT  and  the  Query 
System  Is  jossible  on  one  machine  or  on  separate  machines.  This  suggests 
that  ever.  1  authors  in  various  locations  can  analyze  the  empirical  results 
of  PI.ANIT  lessoi  execution. 

II  CONVERTS  01  TPUT 

The  COSVEM'  soiree  code  contains  one  'WRITE*  statement.  The  output  file 
will  be  written  onto  logical  unit  number  ?  unless  the  ’WRITE'  statement 
has  beet  altered  to  do  otherwise.  The  output  device  can  be  a  card  punch, 
tape  drive,  or  disk,  depending  on  how  the  logical  unit  numbers  are  assigned 


each  physical  device.  The  size  of  the  output  file  can  be  estimated  by 
relating  to  the  size  of  the  PLAN1T  STUDENT  RECORDS  file  which  is  to  be  used 
as  input  to  CONVERT.  Each  recorded  response  to  a  frame  number  will  be 
directly  converted  to  one  80-character  record  of  output.  In  addition  to  this 
there  are  IT  cards  from  an  initialization  file  which  will  be  transferred 
directly  to  the  data  base.  Therefore,  if  the  PLANIT  lesson  contains  100 
t fames  and  IT  students  complete  the  lesson,  the  space  allocation  should  provide 
for  at  least  15  *  100  +  13  *»  1,513  records  of  output.  An  example  of  a 
data  base  which  contains  only  17  records  is  as  follows: 

DATA- HASP  i» 


1.00 

Q 

5 

R 

A 

N 

12077 

720 

LESSON-NAME 

STUDENT- ID 

If 

2.00 

1.00  M 

10 

W 

C 

N 

12077 

720 

LESSON-NAME 

STUDENT-ID 

It 

2 . 50 

2.00  Q 

1 

N 

- 

N 

12077 

720 

LESSON-NAME 

STUDENT-ID 

0 

2.75 

2.50  Q 

65 

R 

B 

Y 

12077 

720 

LESSON-NAME 

STUDENT- ID 

fl 

DEC1.ARF.  FRAME-NO  NUM(1,6)  /» 

DECLARE  LAST-FRAME  NUM(8,13)  It 
DECLARE  FRAME-TYPE  STR(15,15)  If 
DECLARE  RESPONSE-TIME  NUM(16,20)  I 
DECLARE  N-W-R  STR(22,22)  If 
DECI.ARE  TAC  STR(24,24)  If 
DECLARE  CALC  STR(26,26)  It 
DECLARE  DATE  NUM(28,33)  If 
DECLARE  SIGN-ON-TIME  NUM(35,38)  If 
DECLARE  LESSON  STR(39,54)  If 
DL.CI.AL.E  STUDENT-ID  STR(55,70)  If 

V  v 

In  first  i  aid,  'DATA-BASE  If '  ,  is  a  directive  to  the  Query  System  to  allow 
the  operator  to  choose  a  name  for  the  given  data  base.  The  'DECLARE'  cards 


aii  Query  System  format  specifications  for  the  named  variables.  The  NUM(1,6) 


CC-  6 


part  of  the  first  'DECLARE'  statement  indicates  that  the  variable  FRAME- NO 
has  numeric  values  and  it  can  be  found  in  columns  one  to  six  inclusive.  Note 


that  in  the  example  above  the  frame  number 
(i.e.  1.00).  DECLARE  FRAME-TYPE  STR(15,15) 
variable  is  string-valued  and  its  value  is 
four  data  records  shown  above  are  coded  as 


VARIABLE  NAME 

COLUMN 

FRAME- NO 

1-6 

LAST- FRAME 

8-13 

FRAME -TYPE 

15 

RF.SPONSE-TIME 

16-20 

N-W-R 

22 

TAG 

24 

CALC 

26 

DATE 

28-33 

SIGN-ON-TIME 

35-38 

LESSON 

39-54 

STUDENT- ID 

55-70 

are  similar  to  a  FORTRAN  format  F6.2 

indicates  that  the  ’FRAME-TYPE' 

located  in  column  15.  Each  of  the 

follows : 

POSSIB I.E  VALUES 

The  actual  PLANIT  frame 
numbers  with  format  F6.2 

The  previously  executed  frame 
number  with  format  F6.2 

P,  D,  M,  or  Q 

Response  time  in  seconds 

N,  W  or  R  (Neutral,  Wrong  or  Right) 

The  answer  tag  which  identifies 
the  student's  response 

N  or  Y  answering  the  question: 
was  CALC  used  in  this  frame? 

The  date  when  the  student  signed 
on,  in  the  form  MMDDYY 

Time  when  student  signed  on, 
in  minutes  since  midnight 

The  actual  PLANIT  lesson  name 

The  log  in  identity  used  by 
the  student 


The  data  bases  created  by  successive  CONVERT  runs  will  all  be  ~f  the  same 
form.  The  above  attribute  name  list  will  provide  the  operator  with  a  reference 


guide  for  construct inr,  query  statements.  It  is  possible  to  change  the  names 
of  the  attribute  names  by  simply  changing  the  'DECLARE'  cards  in  the  initialization 


file  for  CONVERT  before  running.  The  attribute 
can  consist  of  letters,  digits  and  hyphens  only. 
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III  USING  CONVERT ' S  OUTPUT 

\ftor  CONVERT  has  run  to  completion  the  output  file  can  be  prestored 
into  the  Qviery  System  file  dictionary  by  the  following  command  at  an 
operator's  terminal: 

PRKSTORE  FILE-NAME  ft 

The  FILE-NAME  in  the  PRESTORE  command  can  be  made  up  of  letters,  hyphens 
and  digits  but  it  cannot  contain  spaces.  The  FILE-NAME  will  be  catalogued 
into  the  ss-stem  dictionary  so  that  any  user  can  build  the  data  base  in  his 
work  area.  To  build  a  data  base  at  a  user's  terminal  enter  the  commands: 

DATABASE  DB-NAME  ft 

If 

READ  CARDS  FILE- NAME  ft 

The  first  command  gives  a  name,  DB-NAME,  to  the  data  base  which  is  about  to 
be  built.  Note  that  the  user  can  substitute  any  name  of  his  choosing  for  DB-NAME. 
At  this  point  the  user  is  in  data  base  mode.  A  data  base  can  be  entered 
directly  on  the  user's  keyboard.  In  order  to  read  the  CONVERT  data  base 
from  FILE-  NAME,  the  user  must  exit  data  base  entry  mode  by  entering  a  ft  mark 
ns  shown  above.  The  READ  CARDS  FILE-NAME  ft  command  simply  reads  the  CONVERT 
data  base  from  FILE-NAME  into  the  user's  work  area  under  the  name  DB-NAME. 

The  systei  will  now  accept  query  statements  to  scan  DB-NAME.  If  the  name 
DB-NAME  had  existed  before  the  command  DATABASE  DB-NAME  ft  was  issued,  the 
computer  would  have  responded  with: 

DATA-BASE  NAME  EXISTS.  ADD  TO  THIS  DATA-BASE?  (Y/N) 

A  'N'  response  from  the  user  would  return  him  to  command  mode  where  a  new  name 
could  be  chosen.  If  the  user  had  answei  'Y'  to  the  above  question,  the 
existing  work  area  would  be  concatenated  onto  the  previously  stored  data 
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i  ith  the  nare  DB-NAVE.  This  fs  a  powerful  option  to  which  the  reader  should 
take  note.  This  situation  allows  the  user  to  build  a  data-base  which  contains 
data  from  more  than  ne  PLANIT  lesson.  By  simply  entering  the  name  of  a 
previously  stored  data-base  and  then  answering  ’Y'  to  the  above  question, 
the  user  is  adding  data  to  an  existing  set.  When  a  CONVERT  data-base  has  been 
built  in  the  Query  System  the  information  which  is  in  the  user's  work  area 
is  virtually  the  si.  •  as  the  corresponding  information  which  is  shown  by 
the  PLANIT  'DISPLAY'  co  a:.d  hut  t ho  data  is  collected  over  as  many  students 
and  lessons  as  desired. 

There  are  three  types  of  query  statements  which  are  best  described  by 
the  following  three  exa-ples: 

FOR  DB-NAME  WITH  FRAME-NO  EQ  '  2 '  AND  (N-W-R  EQ  'W'  OR  RESPONSE-TIME 
CT  '10')  I  1ST  STUDENT-ID  RESPONSE-TIME  N-W-R  TAG  - 

COUNT  DB-NAME  WHEN  TAG  EQ  ’-'  * 

LIST  DB-NAME  STUDENT- ID  FRAME- NO  WHEN  TAG  EQ  i1 
The  query  statements  above  are  self  explanatory.  The  second  statement  simply 
counts  the  number  of  records  which  contain  a  '-'  in  the  TAG  field.  The  third 
statement  gives  an  example  of  a  search  for  an  apostrophe.  Instead  of  using 
apostrophes  to  delimit  the  data  value,  the  quotes  were  used.  It  should  be  noted 
that  WHEN  always  follows  the  verb  and  WITH  comes  before  the  verb.  The  first 
query  statement  gives  an  example  of  parentheses  nesting.  The  result  of  this 
statement  will  be  a  list  of  STUDENT-ID,  RESPONSE-TIME,  N-W-R,  and  TAG  which 
occur  on  those  records  whee  the  stated  conditions  are  met.  For  further 
information  on  the  query  statements  the  reader  is  referred  to  the  Query 


System  Manual. 
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IV  DECLARE  JILL  INPUT 

CONVERT  reatL;  both  an  initialization  file  and  a  STUDENT-RECORDS  file  as 

Input  and  writes  a  data  base  as  output.  The  DECLARE  file  serves  a  dual  purpose: 

l)  The  first  card,  (character  set  card),  allows  CONVERT  to  set  up  a  list  of 

the  local  machine's  character  codes.  Each  time  CONVERT  is  installed  on  a  new 

machine  it  has  to  be  able  to  recognize  a  new  set  of  character  codes  internally 

so  that  it  can  process  the  binary  coded  input.  When  the  character  codes  from  the 

first  card  are  read,  CONVERT  associates  them  with  their  respective  characters  by 

their  ordered  column  locatic,ua.  All  of  the  remaining  input  can  be  internally 

identified  by  simply  matching  the  listed  codes  with  their  respective  characters. 

The  DECLARE  file  consists  of  the  following  14  cards: 

01 23456789ABCDEFGHIJKLMNOPQRSTUVWXYZ+-*/ ().%=;:  '(?  //  ?$<>" 

DATA-BASE  // 

DECI.ARE  FRAME-NO  NUM(1,6)  If 
DECLARE  IAST-FRAME  NUM(8,13)  II 
DECLARE  FRAME-TYPE  STR(15,15)  II 
DECLARE  RESPONSE-TIME  NUM(16,20)  II 
DECIARF.  N-W-R  STR(22,22)  II 
DECLARE  TAG  STR(24,24)  II 
DECT, ARE  CALC  STR(26,26)  II 
DECLARE  DATE  NUM(28,33)  II 
DECLARE  SIGN-ON-TIME  NUM(35,38)  II 
DECLARE  LESSON  STR(39,54)  II 
DECLARE  STUDENT-ID  STR(55,70)  II 
$$ 

The  firsL  card  of  the  DECLARE  file  is  used  to  identify  the  local  character 
set.  Each  of  the  remaining  cards  is  written,  exactly  as  shown,  onto 
the  output  file.  The  Query  System  interprets  the  'DECLARE'  statements  as 


field  specifications  for  the  data  variables.  The  second  card,  (DATA-BASE  //) , 
is  vritten  out  as  the  first  record  of  the  data  base.  If  a  name  was  added  to 
this  card  just  before  the  #  sign,  the  Query  System  would  associate  that  name 
with  the  data  base  upon  reading  this  record.  Since  there  is  no  such  name,  the 
Query  System  will  allow  the  operator  to  choose  a  name  for  the  given  data  base. 
Thus,  if  the  operator  wishes  to  append  this  data  base  onto  another  one,  he 
need  only  enter  the  name  of  the  previously  stored  data  base  on  the  terminal 
before  appending  this  data  base. 

The  formatted  'READ'  statement  in  CONVERT  is  set  to  read  the  DECLARE  file 
from  logical  unit  number  _5 .  The  unformatted  'READ'  statement,  used  to  read 
the  PLANIT  STUDENT  RECORDS  file  in  UNLOADed  tape  format,  uses  logical  unit 
number  1_. 

V  STUDENT-RECORDS  FILE  INPUT 

The  PLANIT  STUDENT  RECORDS  file  is  read  one  record  at  a  time  by  an 
unformatted  'READ'  statement.  The  file  is  read  from  logical  unit  number  1_ 
unless  this  'READ'  statement  has  been  altered.  The  student  records  are 
read  in  UNLOADed  tape  format  and  as  mentioned  in  the  introduction  this  may 
be  a  disk  read  depending  upon  how  CONVERT  was  installed. 

The  first  record  of  the  STUDENT  RECORDS  file,  the  Head  Record,  will 
contain  the  PLANIT  lesson  name  and  will  provide  some  parameter  values  which 
are  needed  to  keep  track  of  the  remaining  records. 

If,  for  some  reason,  CONVERT  cannot  read  the  Head  Record,  an  error 
number  will  be  written  onto  the  output  file  and  execution  will  stop.  For  an 
explanation  of  CONVERT’s  error  reporting  facility  see  section  VIII. 
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Except  t  >r  tin*  Hoad  Record,  each  record  in  the  STUDENT-RECORDS  file 
cent  tins  all  the  information  which  is  stored  from  one  student's  execution  of 
a  le<son  In  order  to  prepare  the  STUDENT  RECORDS  file  for  use  in  the  CONVERT 
program,  the  operator  needs  to  'UNLOAD'  the  desired  student  records  while 
PLAN  IT  is  running,  equip  the  resulting  file  with  logical  unit  nunber  1  and 
open  the  file  for  reading.  These  steps  are  part  of  the  procedure  for  executing 
'  ONV • R  r . 

VI  OPERA n NO  1  HE  CONVERT  PROGRAM 


CONCERT'S  oper  iting  procedure  can  be  described  as  a  series  of  steps  as 
t  o  I  1  iws : 

1)  While  rLAN [T  is  running,  'GET'  the  desired  lesson,  'ATTACH'  the 
desired  student  records  and  'UNLOAD'  the  records  into  tape  format. 

21  Equip  the  UNLOADed  file  to  logical  unit  1  and  open  the  device 
for  reading. 

3)  Equip  logical  unit  5  to  the  DECLARE  file  device  and  open  it  for  reading. 

4)  Estimate  t  lie  space  requirement  for  output,  allocate  plenty  of  output 
space  on  logic  il  unit  2  and  open  the  device  for  writing. 

5)  Link  the  1  TBYTE  and  SBYTE  subroutines  to  the  CONVERT  object  deck  and 
run  as  a  batch  job,  one  run  for  each  UNLOADed  file. 

6)  Collect  the  output  data  base  decks  In  the  order  in  which  they  are  to 
be  prestored  tor  the  Query  System. 

7)  Prestore  t  ic  decks  into  the  Query  System  and  build  the  data  base(s) 
arc  >rdin;  to  t  le  Query  System  Manual. 

Ttu  cor; aits  a  the  source  code  should  be  carefully  studied  before  any 
■  •  t  ire  made  t  >  install  CONVERT  on  the  target  machine.  The  comments 

nc lude  an  'ERROR  I  1ST'  in  the  event  that  one  of  the  following  three  execution 


•  i  i  rs  oci  tr  : 
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ERROL  1  -  The  paranii  ter  value  of  VX  does  not  match  the  VX  value  which  was 

calculate^  in  PUYNIT  when  the  student  records  were  produced.  This 
indicates  that  the  input  file  read  from  logical  unit  J_  may  not  be 
the  anticipated  STUDENT  RECORDS  file.  The  user  should  check  to  see 
that  logical  unit  1  is  ready  with  the  correct  student  records  before 
executing  again.  VX  is  a  function  of  BYTWRD  and  VARENT,  two 
parameters  which  must  be  set  in  the  CONVERT  source  code  to  match 
the  values  which  were  used  to  produce  the  student  records.  The 
user  should  check  to  be  sure  that  the  BYTWRD  and  VARENT  values  are 
identical  to  those  set  in  PLAN1T. 

ERROR  2  -  The  user  should  check  logical  unit  1  to  be  sure  it  is  ready  with 

the  corri ct  STUDENT  RECORDS  file.  Error  2  will  occur,  if  the  Head 
Record  is  not  exactly  3  *  VX  +  1  words  in  length. 

ERROR  3  -  The  user  should  check  the  input  file  on  logical  unit  to  be  sure 

that  it  is  ready  with  the  correct  STUDENT  RECORDS  file.  The  BYTWRD 
val  je  which  was  set  in  FLANIT  r..ost  be  the  same  as  the  value  set  in 
the  C0NV1 RT  source  code. 

In  the  event  that  an  error  occurs,  the  error  number  will  be  printed  on 
the  output  unit  an<(  execution  will  stop.  The  error  checking  is  most  effective 
for  spotting  the  p  oblems  which  can  occur  during  the  first  attempt  at  executing 
C0N1ERT,  immediate  y  following  the  installation. 

VII  INSTALLING  CONCERT 


Each  of  the  p  ojrams  which  are  coded  in  the  FORTRAN  META  language  can  be 

installed  on  a  tar  ;et  machine  by  following  the  same  technique.  Meta  language 

package:  include  Pl.ANIT,  The  On-Line  Query  System,  The  M10P  Test  Program  and 

CONVERT.  Th«  CONVERT  installation  requires  the  following  steps: 

-  Writing  the  I.DBYTF  and  SBYTE  subroutines  or  obtaining  them  from  a 
previously  installed  version  of  PLANIT  or  the  Query  System  on  the 
tai  get  ir  ichitie 
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-  Running  the  PI  AN  IT  Generator  Program  to  produce  the  CONVERT  FORTRAN 
code . 

-  Compiling  the  FORTRAN  code  and  linking  the  object  deck  to  the  LDBYTE 
and  SBYTK  subroutines. 

The  PLANIT  Installation  Manual  provides  more  information  concerning  the 
above  steps  and  the  reader  is  advised  to  read  the  following  sections  before 
attempting  to  install  CONVERT: 

-  PART  Ill  CHARACTER  HANDLING:  LDBYTE  AND  SRYTF. 

Sections  13.0  and  14.0 

PART  IV  1’IANIT  SYSTEM  GENERATION 
Sections  13. 0,  16.0,  17.0  and  18.0 

The  in*  callati  >n  of  CONVERT  on  the  target  machine  requires  only  a  subset 
.■I  :  to  r. tops  needed  to  install  PLANIT.  The  LDBYTE  and  SBYTE  subroutines  which 
wen  written  for  FLANIT  can  be  used  for  CONVERT  with  no  change,  if  prepared 
as  directed.  CONVERT  requires  no  MIOP  subroutine  and  there  is  no  need  for  a 
t.b.K  file  for  use  in  the  generation  step.  The  only  parameters  which  need  to 
he  t  for  generation  are  BYTWRD,  VARENT  and  CRDSZE  and  these  are  explained  in 
the  listing  comments.  The  source  code  contains  comments  which  emphasize  the 
■  tatements  which  need  to  be  examined.  There  are  two  ’READ’  statements,  one 
’WRITE'  and  one  'FORMAT'  statement  in  the  source  code  which  should  he  examined 
to  insure  that  they  qualify  as  legal  FORTRAN  statements  on  the  target  machine. 

Although  the  input  unit  1  is  normally  considered  to  be  magnetic  tape 
id  the  output  unit  2,  (the  resulting  data  base)  is  described  as  cards,  either 
or  both  of  then  might  be  a  disk  file,  if  the  installer  so  chooses.  The 
: .  >  I  i  '  up,  fable  defines  the  requirement  for  the  unit  numbers:  _________ 
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Logical  Unit  Number  Logical  File 

1  Input  data  file  consisting  of  the  PLANIT  UNLOAD 
tape  format  of  the  selected  set  of  student 
records 

2  Output  data  file  formatted  as  80-character 
card  images  consisting  of  the  Query  data  base 
version  of  the  student  records 

5  Input  data  file  consisting  of  the  initialization 

DECLARE  file  described  in  section  IV 
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ABSTRACT 


This  paper  is  a  description  of  a  program  which  is 
design  to  help  those  programmers  who  are  attempting  to 
install  PLANIT  or  another  PLANIT-like  operating  system. 
The  program  of  concern  is  called  the  MIOP  Interface 
Test  Program  and  is  used  to  test  the  MIOP  subroutine  (a 
locally-written  subroutine  necessary  for  local  PLANIT 
execution).  The  description  herein  contains  answers  to 
the  following  questions: 

•  What  is  the  MIOP  Test  Program  designed  to  do? 

•  Where  does  the  use  of  such  a  program  fall  within 
the  sequence  of  steps  which  should  be  used  to 
install  PLANIT? 

•  How  is  the  Test  Program  installed  and  used  most 
efficiently? 

•  What  are  the  functional  characteristics  of  the 
tests  which  are  administered  by  the  Test  Program? 
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THE  MIOP  INTERFACE  TEST  PROGRAM 


I.  INTRODUCTION 


This  document  describes  the  operation  of  the  MIOP 
Interface  Test  Program,  a  program  which  exercises  the 
locally-written  machine  interface  subroutine  for 
PLANIT. 

Many  people  have  become  somewhat  familiar  with 
TLANIT  by  now.  PLANIT  is  a  time-sharing  system  designed 
for  instruction  via  a  computer,  and  is  completely 
portable  such  that  any  qualified  system  programmer 
can  install  it  on  a  local  machine  by  writing  three  inter¬ 
face  subroutines.  Two  of  them,  LDBYTE  and  SBYTE,  are 
quite  trivial  and  offer  little  challenge.  The  third, 

MIOP  (Machine  Input/Output  Program),  is  somewhat  more 
involved,  usually  requiring  two  weeks  or  more  to  produce. 
MIOP's  functxon  is  to  perform  all  data  transfers  between 
PLANIT  and  the  peripheral  devices. 

What  may  be  less  well  known  is  that  PLANIT  consists 
of  both  an  author  language  and  a  time-shared  operating 
system.  In  fact,  the  operating  system  has  been 
extracted  from  PLANIT  and  is  being  used  for  new  appli¬ 
cations.  MIOP  interfaces  that  operating  system  to 
local  hardware  so  that  the  exact  nature  of  the  applica¬ 
tion  program  which  uses  MIOP  will^  usually  be  completely 
transparent  to  the  system  programmer  who  codes  it. 

It  is  no  surprise  that  MIOP  should  be  coded  in  as 
efficient  a  manner  as  possible,  and  must  perform 
exactly  the  operations  which  the  PLANIT  operating  system 
assumes.  Rather  than  attempting  to  familiarize  the 
system  programmer  with  PLANIT  (or  other  PLANIT-like 
application  programs),  this  MIOP  Interface  Test  Program 
was  developed  which  systematically  exercises  all  of  the 
required  interface  points  between  PLANIT' s  operating 
system  and  the  peripheral  devices.  Where  possible,  this 
program  also  performs  some  checks  on  the  efficiency  with 
vhich  the  operations  are  being  executed.  The  system 
programmer  who  is  doing  the  local  installation  can  use 
this  program  to  check  the  work  without  having  to  know 
or  use  PLANIT  in  order  to  do  it,  even  checking  the  MIOP 
irore  thoroughly  and  in  much  less  time  than  if  PLANIT 


was  used  to  do  it. 
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Therefore,  the  installer  is  encouraged  to  invest 
the  little  extra  time  that  will  be  required  to  run 
this  test  program  in  order  to  greatly  simplify  the 
checkout  process  for  the  newly  written  MIOP  code. 

The  same  LDBYTE  and  SBYTE  subroutines  that  are 
needed  for  PLANIT  are  also  needed  for  the  test  program. 
If  these  are  not  correct,  none  of  the  programs  will 
run.  However,  there  is  not  too  great  a  chance  for 
error  and  a  check  of  a  core  dump  will  quickly  verify 
whether  they  do  in  fact  work  properly.  It  is  up  to 
the  installer  to  make  them  operate  as  efficiently  as 
possible.  The  PLANIT  Installation  Manual  contains  a 
description  of  each  of  t lie  subroutines  mentioned  and 
the  PLANIT  tape  contains  FORTRAN  versions  of  them  as 
well.  These  are  not  intended  to  be  used  as  such,  but 
to  help  the  installer  understand  the  logic  and  avoid 
coding  errors.  The  actual  coding  can  almost  certainly 
be  done  more  efficiently  in  assembly  language  to 
minimize  execution  time. 


II.  TESTING  THE  PROPER  OPERATION  OF  MIOP 


It  is  MIOP’s  duty  to  access  (read,  write,  open  and 
close)  each  of  the  devices  which  will  be  needed  to  run 
the  operating  system  for  PLANIT.  In  addition,  MIOP  must 
be  able  to  retrieve  the  current  date  and  time,  suspend 
the  execution  of  the  operating  system  during  periods 
of  inactivity,  and  respond  to  interrupts  which  are  gener¬ 
ated  by  user  terminals.  The  MIOP  Test  Program  simulates 
the  operating  system  by  making  a  series  of  calls,  each 
of  which  checks  MIOP's  ability  to  perform  the  desired 
opt  ration.  If  any  of  the  calls  results  in  a  failure 
to  perform  the  designated  operation  (e.g.  failure  to 
op.n  a  file,  read  error,  write  error,  etc.)  the  Test 
Program  will  respond  with  a  comment  about  the  error. 

The  comment  will  be  sent  to  the  operator’s  terminal,  if 
possible,  or  the  line  pringer  otherwise.  As  mentioned 
in  the  Test  Program's  comment  cards,  the  line  printer  will 
be  used  to  document  all  testing  progress  until  the 
terminal  becomes  active.  If  a  MIOP  failure  prevents  the 
MIOP  Test  Program  from  communicating  to  the  printer,  then 
the  Test  Program  will  proceed  to  its  termination  with 
a  "fatal  error"  call  to  MIOP  and  the  installer  can  cause 
a  core  dump  to  cH  splay  the  necessary  debugging  informa¬ 
tion.  The  erroi  number  for  a  "fatal  error"  will  be 
transmitted  to  MIOP  in  the  format  described  in  the 


PLANIT  Installation  Manual.  The  explanation  of  these 
error  numbers  is  found  in  the  comments  section  of  the 
program  listing  for  the  MIOP  Interface  Test  Program. 

Also  in  the  comments  will  be  found  the  annotation  of 
the  first  few  calls  which  will  be  made  to  MIOP.  It 
is  crucial  that  MIOP  is  able  to  execute  these  calls 
successfully  so  that  the  Test  Program  can  begin  to 
communicate  with  the  operator,  first  through  the  line 
printer  and  then  at  the  terminal. 

Once  the  MIOP  Test  Program  has  completed  its 
battery  of  tests,  it  will  respond  with  a  "BOX  SCORE" 
list  of  the  operations  which  '.ere  tested  and  whether 
or  not  the  tests  were  successful.  Unless  the  entire 
sequence  of  MIOP  calls  are  pe 'formed  with  no  problems, 
the  operator  may  wish  to  modi fy  the  MIOP  code  and  rerun 
the  Test  Program.  To  simplify  this  process,  the  operator 
is  given  the  option,  near  the  beginning  of  the  testing 
sequence,  just  after  terminal  communication  has  been 
estaMisied,  to  branch  to  various  entry  points  within 
the  prescribed  sequence  of  tests.  Also,  the  testing 
sequence  may  be  stopped  e*.  any  point  by  typing  the 
word,  "STOP"  on  the  terminal. 


III.  THE  MIOP  TEST  PROGRAM  AS  AN  AID  TO  SYSTEM  INSTALLATION 


MIOP  will  require  direct  disk  access.  To  run  the 
tests  it  is  important  that  space  be  allocated  on  disk 
as  intended  for  PLANIT  (probably  before  running  the 
MIOP  Test  Program).  It  is  possible  to  write  a  MIOP 
subroutine  in  such  a  way  that  disk  space  will  be  alloc¬ 
ated  as  needed  in  which  case  no  preliminary  allocation 
would  be  necessary.  However,  the  more  common  method 
seems  to  use  a  fixed  allocation  of  disk  space  which  is 
catalogued  prior  to  PLANIT’s  execution,  in  which  case 
the  installer  will  need  to  generate  the  PLANIT  system 
code  in  order  to  obtain  disk  record  size  parameters. 
After  choosing  appropriate  machine  parameters  and 
after  generating  the  PLANIT  code,  the  installer  can 
find  record  sizes  for  each  of  the  PLANIT  disk  files 
within  the  generated  code  version  of  PLANIT' s  OFILE 
procedure.  If  the  record  size  happens  to  be  zero  (as 
is  usually  the  case  for  file  number  seven),  the 
^■responding  file  number  will  not  be  used.  The 
MAXRECSZE  parameter  in  the  MIOP  Test  Program  listing 
is  to  take  on  the  value  of  the  largest  PLANIT  record 
size  (i.e.  the  file  number  six  record  size).  Thus, 
the  in  taller  will  need  the  record  size  data  for  PLANIT 
in  order  to  properly  specify  this  one  parameter  for  the 
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generation  of  the  MIOP  Test  Program.  (See  also  the 
PLANIT  Installation  Manual,  Appendix  C) .  This  disk 
file  information  is  needed  to  allocate  disk  space  that 
will  be  used  both  by  the  Test  Program  and  by  PLANIT. 

The  same  information  could  also  be  obtained  from  the 
COMMON  Map  which  the  PLANIT  Generator  program  will 
cause  to  be  printed  when  the  PLANIT  code  is  generated. 

The  following  check  list  is  recommended  as  a  guide 
for  the  order  of  events  in  the  installation  process: 

•  Read  the  PI.ANIT  Installation  Manual,  noting 
particularly  the  IORST  array  values  for  each 
cal  1 . 

•  Read  Lae  comments  on  the  system  source  code 
listing. 

•  Write  the  LDBYTE  and  SBYTE  subroutines. 

•  Choose  parameters  for  PLANIT  s  Merge  File. 

•  Generate  the  Fortran  code  and  the  COMMON  Map 
for  PLANIT.  Note  that  the  PLANIT  Generator 
also  uses  the  same  LDBYTE  and  SBYTE  subroutines 
so  they  will  be  correct  when  the  Generator  runs 
properly . 

•  Obtain  the  disk  file  numbers  and  record  sizes 
for  each  from  the  generated  OFILE  procedure, 
and  choose  the  number  of  records  that  you  wish 
to  allocate  for  each  file.  Note  that  some 
will  be  fixed  by  system  parameters  and  some 
will  be  optional,  depending  on  how  much  user 
space  is  to  be  made  available. 

•  Write  the  MIOP  subroutine  code. 

•  Read  the  comments  on  the  MIOP  Interface  Test 
Program  listing. 

•  Choose  the  Merge  File  parameters  for  the  MIOP 
Test  Program.  Note  that  most  values  will  be 
the  same  as  in  PLANIT. 

•  Generate  the  MIOP  Test  Program. 

•  Allocate  space  on  disk  according  to  the  file 
number  and  record  size  data  acquired  earlier. 


•  Put  the  MIOP  Test  Program's  Cards  Filo  in 
place  so  it  can  be  road. 

•  Compile  and  run  the  MIOP  Test  Program,  using 
it  to  debug  MIOP. 

•  It  may  be  necessary  to  generate  PLANIT  again, 
this  time  implementing  the  correct  overlay 
structure.  If  changes  to  any  parameters  are 
necessary,  the  disk  record  sizes  may  change 
requiring  a  reallocation  of  disk.  This  should 
not  affect  the  MIOP  though  unless  the  record 
sizes  are  used  as  literal  numbers  in  the  MIOP 
code.  It  would  be  better  not  to  have  them  show 
up  as  literals  in  the  MIOP  code  for  that  reason. 

•  Compile  the  generated  PLANIT  code,  linking  it 
with  LDBYTE,  SBYTE  and  MIOP. 

u  Make  any  necessary  changes  in  PLANIT' s  Cards 
File  and  put  it  in  place  to  be  read  by  the 
PLANIT  program. 

•  Run  PLANIT. 


IV.  INSTALLATION  OF  THE  MIOP  TEST  PROGRAM 


Installation  of  the  MIOP  Interface  Test  Program 
should  proceed  smoothly  after  the  installer  has 
generated  the  PLANIT  system.  As  was  mentioned  before, 
the  Tost  Program  installs  exactly  like  PLANIT,  using 
the  same  generation  process  and  of  course,  the  same 
three  subroutines,  LDBYTE,  SBYTE  nnd  MIOP.  However, 
the  Test  Program  will  have  fewer  installation 
parameters  to  set  than  PLANIT,  and  will  usually  not 
require  the  overlay  logic,  since  tho  entire  program 
should  normally  fit  into  core.  Thus,  tho  Merge  File 
for  the  Test  Program  is  very  brief,  and  any  questions 
about  particular  parameter  values  can  usually  be 
resolved  by  referring  to  the  corresponding  parameters 
in  PLANIT,  noting  their  description  in  ttie  PLANIT 
source  code  listing. 
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V  .  DKSCR I PT ION  O F  THE  TESTS 


Throughout  the  sequence  of  MIOP  tests,  the  Test 
Program  will  check  to  see  that  the  IORST  array  value 
which  have  been  set  for  MIOP's  use  have  not  been 
altered  during  the  call.  Then  the  status  word  is 
checked  to  confirm  MIOP's  report  of  its  work,  and 
the  user  is  notified  of  any  problems,  which  might 
be  occasioned  eithei*  by  MIOP's  report  of  an  error 
ox*  by  an  internal  evaluation  of  the  results  which 
wove  expected  from  the  call.  The  sequence  of  tosts 
which  are  administered  to  MIOP  is  as  follows: 

1.  Open  the  line  printer. 

2.  Open  the  Cards  File. 

3.  Read  the  fii*st  card. 

4.  Print  a  copy  of  the  first  card  on  the  line 
printei*.  The  operator  should  visually 
confirm  that  the  printer  has  executed  a 
page  eject  just  px*ior  to  printing  this 
line  so  that  the  line  appears  just  below 
the  pei* fora t ion  in  the  paper. 

5.  Print  the  message,  ’’1ST  CARD"  on  the  line 
printer.  The  opei*ator  should  check  for 
any  misprints.  This  will  be  enough  to 
confirm  that  the  data  on  the  remainder  of 
the  cai*ds  will  read  properly. 

6.  Read  and  process  each  of  the  remaining 
cards  in  the  Cards  Filo. 

7.  Close  the  Cards  File. 

8.  Print  a  comment  (on  the  line  printer) 
i*egarding  the  closing  of  the  Cards  File 
and  the  operations  that  will  take  place 
next . 

{).  Open  the  operator's  terminal. 

10.  Px*int  a  comment  (on  the  line  printer) 

regarding  the  opening  of  the  opei*ator's 
t  erminal . 
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11.  Road  the  operator's  terminal.  The  operator 
is  asked  to  type  the  word,  "HELLO",  and  then 
to  confirm  whether  the  text  appeared  at  the 
terminal  properly.  These  first  eleven  steps 
are  critical  in  establishing  conununica t ion 
with  the  operator  so  that  further  testing 
can  be  done  on  an  interactive  basis.  Any 
failures  to  this  point  will  be  documented 

on  the  line  printer.  Note  that  in  all 
cases  where  a  YES  or  NO  response  is  requested, 
a  "Yr"  or  "N"  abbreviation  may  be  used. 

12.  Send  two  or  more  buffers  of  text  to  the 
terminal.  This  will  test  the  proper  use  of 
carriage  control  characters  on  the  terminal. 

13.  Next  is  the  carriage  return  test.  This  test 
will  only  be  made  if  the  "line  feed"  and 
"carriage  return"  are  distinct  characters. 

It  will  test  a  carriage  return  without  a  line 
feed. 

14.  The  enforced  time  limit  test  is  part  of  the 
question  which  asks  whethex*  the  enforced 
timed  terminal  x*ead  lias  been  implemented. 

If  not,  answei’  "NO"  and  proceed.  Otherwise 
the  operator  will  bo  timed  at  20  seconds 
for  a  response.  There  will  be  three  opport¬ 
unities  to  experiment  with  this  test,  so 

an  answer  can  be  given  before  the  20  seconds 
have  expired  on  one  tx*y  a.id  then  the  opei*ator 
can  wait  and  time  the  20-second  interval  on 
another  try.  Any  response  submitted  before 
the  20  seconds  have  expired  should  be  accepted 
immediately. 

15.  The  terminal  writing  speed  test  sends  each 
letter  of  the  alphabet  sepai’ately,  one  letter 
pox*  MI0P  terminal  write  call,  along  with  a 
question  to  the  terminal.  The  operator  will 
probably  notice  a  slower  typing  speed  on  the 
alphabet  string  than  on  other  messages.  However, 
if  the  speed  appi’oaches  one  character  per  second, 
chances  are  that  MIOP's  data  handling  of  messages 
to  the  tex*minal  will  adversely  affect  the 
apparent  response  time  of  PI.ANIT. 
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16.  The  blank  line  test  pertains  to  PLANIT* s 
need  to  detect  blank  lines.  Since  trail¬ 
ing  blanks  are  to  have  been  eliminated 
from  the  character  count  of  all  incoming 
terminal  reads  to  PLANIT,  a  line  in  which 
all  typed  characters  are  blanks  must  be 
the  same  as  the  line  where  no  key  other 
than  the  carriage  return  is  pressed.  It 
would  be  well  to  try  both  variations. 

One  form  can  be  used  for  the  response  to 
this  test.  Then,  a  blank  line  can  be  given 
in  response  to  any  of  the  following  tests. 

If  the  line  is  recognized  as  blank,  the 
Test  Program  will  just  ask  for  the  answer 
again . 

17.  The  Test  Program  will  attempt  to  retrieve 
the  time  and  date  from  a  MIOP  call.  These 
will  be  printed  on  the  terminal  for  the 
operator  to  check  visually.  No  additional 
comments  will  be  made.  One  variation  allows 
the  setting  of  the  date  to  be  deferred  until 
PLANIT  is  running.  In  that  case,  the  date 
printed  in  this  test  may  be  incorrect. 

18.  The  system  WAIT  test  is  next.  Since  the 
MIOP  Test  Program  is  attempting  to  simulate 
PLANIT,  it  is  important  that  its  execution 
be  suspended  while  the  program  is  inactive 
(waiting  for  a  user  input),  so  that  CPU 
time  is  given  to  other  programs.  This  is 
tested  by  reporting  to  the  terminal  the  count 
of  SYSTEM  WAIT  calls  and  the  elapsed  time  of 
the  longest  one.  A  WAIT  call  will  occur  for 
each  batch  of  text  that  goes  to  the  terminal 
plus  one  more  when  the  terminal  is  idle.  To 
get  the  most  value  from  this  test,  delay  your 
response  and  time  the  delay.  About  30-40 
seconds  should  be  sufficient.  The  time  report¬ 
ed  should  correspond  to  your  observation.  The 
number  of  WAIT  calls  could  vary  up  to  a  half 
dozen  or  so.  However,  if  execution  is  not 
being  suspended,  the  count  would  probably 

be  large,  indicating  that  looping  is  taking 
place  and  the  WAIT  call  is  being  made  re¬ 
peatedly.  Many  machines  have  a  "system 
wait"  light  on  the  console  which  can  also  be 
checked  during  these  intervals.  Note  that 
the  time  test  (in  no.  17,  above)  must  be 
correct  for  this  and  futui'e  timed  tests  to 
be  reliable. 


DD-  9 


19.  The  line  printer  is  now  closed. 

20.  Next,  the  operator  is  asked  to  enter  the 
number  of  records  and  record  sizes  for  each 
o :  the  disk  files.  The  record  sizes  can  be 
obtained  from  the  PLANIT  OFILE  procedure  (the 
generated  FORTRAN  version) ,  or  from  the 
Generator  COMMON  Map  by  using  the  listing 
comments  to  snow  the  data  items  and  arrays 
belonging  to  each  file.  The  number  of 
recoi’ds  given  in  the  reply  can  be  less  than 
the  actual  number  which  have  been  allocated 
on  disk,  but  cannot  be  more.  The  actual 
number  of  records  will  also  need  to  be  shown 
ii  PLANIT's  Cards  File,  on  the  "1FBTN"  card. 

I f  the  numbers  for  that  card  have  been  chosen 
aid  the  corresponding  records  allocated  on 
disk,  then  a  legal  reply  would  be  to  reproduce 
t  lat  card,  character  by  character. 

Tie  number  of  records  (e.g.  the  "IFBTN"  card) 
will  be  requested  first,  then  the  record  sizes 
will  be  requested  for  all  files  whose  number 
of  records  were  non-zero.  It  is  important  that 
nine  of  the  record  sizes  exceed  the  value  given 
fir  the  "MAXRECSZE"  parameter,  and  that  the  file 
nimber  six  record  size  exactly  equal  it. 

21.  Each  of  the  disk  files  (containing  non-zero 
record  counts)  is  opened,  a  message  on  the 
terminal  confirms  the  operations. 

22.  The  operator  is  now  given  a  choice  of  testing 
all  records  of  each  file  or  a  sample  of  not 
more  than  three  records  in  each  file.  The 
sample  should  be  enough  to  confirm  MIOP's 
work  and  will  run  faster.  However,  it  would 
be  better  if  a  little  extra  processing  time 
can  be  tolerated,  to  check  all  records  since 
this  will  also  confirm  whether  all  records  are 
properly  allocated  and  that  no  disk  parity 
errors  are  found. 

23.  Each  file  will  be  tested  in  order,  testing  its 
records  one  at  a  time  up  to  the  number  that  are 
to  be  checked.  The  checks  include  writing  and 
reading  distinguishable  data,  confirming  direct 
access  of  the  right  data  from  a  given  record 
number,  looking  for  overwriting  and  underwriting, 
?nd  verifying  the  return  status  number.  If  any 


L 
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errors  are  found,  a  message  describing  the 
error  along  with  the  file  and  record  number 
where  it  occurred,  will  be  reported  on  the 
terminal.  If  more  than  five  errors  of  any 
kind  are  detected,  the  disk  check  will  be 
terminated.  I f  no  errors  are  encountered, 
the  successful  write  and  read  of  the  first 
record  of  each  file  will  be  reported  on  the 
terminal.  This  will  enable  the  operator  to 
follow  the  progress  of  the  test.  Records 
beyond  the  first  will  not  be  reported  (unless 
errors  are  encountered)  because  of  the  amount 
of  terminal  output  which  would  be  generated. 

24.  If  the  MIOP  Test  Program  has  been  generated 
for  more  than  one  user  and  if  the  "MAXRECSZE" 
parameter  is  equal  to  the  file  number  six 
record  size  and  if  no  errors  were  encountered 
while  checking  file  six  records,  then  time¬ 
sharing  may  be  tested.  The  operator  (or 
some  assistants)  may  begin  interacting  at 
other  terminals.  The  test  scenario  will 
continue  only  on  the  operator's  terminal. 

The  remaining  terminals  will  simply  acknow¬ 
ledge  inputs  by  reporting  back  the  number  of 
characters  in  the  input. 

25.  Next,  the  operator  will  be  asked  if  magnetic 
tape  support  has  been  implemented  in  MIOP. 

If  so,  a  request  will  go  to  MIOP  for  a  tape 

to  be  mounted.  This  should  be  a  scratch  tape. 

If  not  implemented,  the  tape  test  will  be  skipped. 

26.  After  the  mount  has  been  confirmed,  the  tape 
unit  will  be  opened. 

27  Now,  five  records  will  be  written  on  tape. 
Arbitrary  record  sizes  have  been  chosen  for 
each  of  the  five  records  of  4,  16,  64,  256  and 
1024  words. 

28.  A  call  will  be  made  for  write  end-of-file, 
close  and  rewind. 

29  The  tape  will  be  re-mounted,  re-opened  and 

five  records  will  be  read.  The  check  includes 
confirming  the  data  from  each  record,  checking 
overwrites,  underwrites  and  the  presence  of 
the  end-of-file  mark  after  the  fifth  record. 

Also  the  MIOP  status  reports  will  be  checked. 

The  results  will  be  reported  to  the  terminal. 


30.  The  tape  unit  will  be  closed  (read-type) 
and  rewound.  (The  rewind  operation  is 
implied  in  each  close  call,  for  reading 
or  writing) . 

31.  Next,  the  operator  is  asked  whether  the 
card  punch  and  read  operations  can  be  tested, 
and,  if  so,  to  ready  the  card  punch  before 
typing  the  reply.  If  not,  the  Test  Program 
skips  to  the  end  where  the  "BOX  SCORE”  is 
printed. 

32.  The  card  punch  unit  is  opened,  and  the  status 
result  is  tested. 

33.  One  card  is  punched.  The  characters  on  the 
card  are  similar  to  the  first  line  on  the 
line  printer. 

34.  The  card  punch  unit  is  closed. 

35.  Now,  the  operator  is  given  time  to  position 
the  punched  card  in  the  card  reader  unit. 

A  question  at  the  terminal  asks  if  the  card 
is  ready  to  be  read.  The  card  should  be  in 
position  before  replying.  However,  if  the 
reply  to  the  question  is  "NO",  the  remainder 
of  the  test  will  be  skipped. 

36.  The  card  reader  unit  is  opened  and  checked. 

37.  The  card  is  read  and  the  data  compared  to 
that  which  was  punched.  (Note  that  the  card 
can  also  be  interpreted  for  visual  checking.) 

38.  The  card  reader  unit  is  closed. 

39.  A  "BOX  SCORE"  summary  of  test  results  for 
those  features  which  were  tested  will  be 
printed.  When  the  BOX  SCORE  proclaims  all 
tests  to  be  satisfactory,  MIOP  is  ready  to 
be  linked  with  PLANIT. 

40.  All  remaining  opened  files  are  closed  and 
the  Test  Program  is  stopped. 


Having  successfully  completed  all  of  the  tests,  the 
installer  may  be  reasonably  confident  that  the  MIOP 
coding  is  correct.  Unfortunately,  though,  this  does  not 
confirm  that  it  is  as  efficient  as  it  might  be,  but  at 
least  it  will  run  so  that  PLANIT  will  run  and  efficiency 
questions  can  then  be  explored. 
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DEMONSTRATION  DATA  BASE 
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DEMONSTRATI ON  DATA  BASK 


The  following  pages  contain  a  description  and 
listing  of  the  Demonstration  Data  Base,  GOBBA  (Ground 
Order  Of  Battle).  The  data  base  is  described  both 
in  the  chart  on  the  next  page  and  in  the  data  base 
attribute  name  declarations  on  the  final  page  of 
the  data  base  listing. 

The  listing  assumes  80-column  cards  as  the  input 
medium,  where  each  group  of  three  lines  (terminated  by 
a  character)  constitutes  a  240-column  (3  x  80) 

entry  into  the  data  base. 

The  description  of  the  syntax  for  the  DECLARE  and 
DEFINE  statements  can  be  found  in  the  Portable  Query 
System  User’s  Manual. 
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DATA-BASE  GOBBA  * 

13  CAA  KLIENTO  9401 54ST  LAURENCOKOVALSK I 

ZITNIKOV  G/A  NE  CANADA 

70  675  745121111  9 

48  CAA  804 74  1ST  LAURENCOKOV.ALSK I 

TRI MPER, L  G/A  NEV  ENGLAND  NEV.  YORK 

*  81  796  877221221  # 

21  CAA  AFANADORO  10 770 1ST  LAURENCOKOVALSKI 

NAZZRHULLAH  G/A  NEV.  ENGLAND  NEV  YORK 

72  734  806111111  9 

16  TK  A  INFERULARO  741088ST  LAURENCOKOVALSKI 

GRIMALDI , G  G/A  NEV  YORK 

27542272525479111111  9 

15  AIR  A  628808ST  LAURENCOKOVALSKI 

NE  CANADA  NEV  ENGLAND 

670  6005  66751 11221  9 

6  7  ABN  DIV  KAPULO  243567ST  LAURENCOKOVALSKI 

MAINE 

855  8212  906732100212 VK 60%  ASSIGNED  PERSONNEL  9 

53  ARTY  DIV  ATESTI  1  1  748 1ST  LAURENCOKOVALSKI 

NEV  ENGLAND  CANADA 

46 3  441  7  4880121 1 1215VK70*  ASSIGNED  PERSONNEL  9 

14  SSM  DIV  621113ST  LAURENCOKOVALSKI 

ARCOVI TO, SV  G/D  NEW  ENGLAND 

495  431 5  46101 1 1 1 1 1  0 

24  SSM  DIV  KAPO  542449ST  LAURENCOKOVALSKI 

NEV  ENGLAND 

463  4010  44731 1 1001  9 

41  SAM  DDE  DUONALFO  3094 75ST  LAURENCOKOVALSKI 

BAT  ALOV, B  G/B  CANADA 

183  2019  22021 11111  9 

72  SAM  BDE  512345ST  LAURENCOKOVALSKI 

CANADA 

1 78  1928  21061 1 1001  9 

15  ENG  CONST  REGT  691703ST  LAURENCOKOVALSKI 

NEV  ENGLAND 

107  798  905000001  9 

.  85  ENG  AMPH  REGT  DHATUR  083458ST  LAURENCOKOVALSKI 

NEV  ENGLAND 

90  901  991000001  9 

,  24  SIC-  REGT  2776 74ST  LAURENCOKOVALSKI 

PUTTENHAM  COL  NEV  ENGLAND 

317  1687  2004000001  9 

62  MT  REG!  130251  ST  LAURENCOKOVALSKI 


G/A’S 

G/A  ’S 

G/A’S 

G/A  ’S 

G/A  *S 

G/A  'S 

G/A  *S 

G/A  *S 

G/A’S 

G/A  *S 

G/A’S 

G/A’S 

G/A  ’  S 

G/A’S 

G/A’S 


NEV  ENGLAND 


166  1395  1561000001 

5  CAA  K0L0HI0  SO  5  72 1 GOLFO 

SOVAK.JJ  C/A  TEXAS  OKLAHOMA 

71  721  792111211 

6  CAA  FENDIC-A  600  731  GOLFO 

FF.nLI  NC-HE7  T1  »L  G/A  LOUISIANA 

69  673  742111111 

1  TK  A  AKOKPANI  802 1 73G0LF0 

NEBBIA*TC  C/A  1 EXAS  OKLAHOMA 

25592302125580 llllll 

2  TK  A  ANGULO  200712G0LF0 

ULIAN'jV*N>  G^A  TEXAS  LOUSIANA 

27602409826858321  1  1221 Vrt75X  ASSIGNED  TANKS 

2  AIK  A  RETOFORMA  108756G0LF0 

RADESCU*  SG  G/AIRTEXAS 

655  5987  6421 11111 

1  ABN  DIv  TASO  32  5  70  7G0LF0 

VUAN/HJ  G/D  TEXAS 

861  8175  9036112222  9VK55X  ASSIGNED  PERSONNEL 

2  ARTY  DIV  FLUEGO  20061 3G0LF0 

ODONEZ*  JS  G/D  TEXAS  OKLAHOMA 

478  4392  487021 1 1 1 1 


55  SSM  DIV  APi'.AMUNI  TO 

JEN*  Vs  G/D  TEXAS 

479  4165  46441 11111 

951 605G0LF0 

1  SAM  DDE  DRAGON 

TEXAS 

1 79  2020  2199111001 

80  5804G0LF0 

3  SAM  DDE  THOMPETO 

TEXAS 

1 77  1840  2017111111 

92 1 3 1 3G0LF0 

2  CML  DDE 

TEXAS 

145  1801  19461 11111 

604  780 GOLFO 

9  ENG  AMPH  hLGT 

TEXAS 

103  605  908111001 

9  504  3  SGOLFO 

2  SIG  REG! 

TEXAS 

301  1683  1984000001 

45547 7G0LF0 

10  Ml  REGT  TFSTUDO 

TEXAS 

163  1366  1529000001 

31 732 SGOLFO 

8  MED  REGT 

8699 59 GOLFO 
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G/A'S 
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0  'ROJRKE*  TJ 
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0  'ROURKE*  TJ 

G/A'S 

TEXAS 


<r  to 


66  291  357000001 

7  INTEL  REGT  35841 8G0LF0 

TEXAS 

65  278  34300000 1 

2  POND  BN  853018G0LF0 

TEXAS 


98  326  42400000 1 

1  CAA 
SANCHEZ, F  G/A 

76  728  80400000 

3  CAA 

GULLS T  -. AND,  SL  G/A 
79  750  82900000 

12  CAA 

SCHUSCFNIGG  G/A 

69  713  78211122 

9  A  1:1  A 

POv.  ELL,  J6  G/A  I 

666  6003  6671  111  1  1 

4  AF'N  DI  v 


1 0  5  70 1 KAR I  BO 
CAROLINA 

30571  1 KAR I  BO 
CAROLINA  GEORGIA 


OHELO 
NORTH 

1 

EC-ECO 
SOUTH 

1 

201 71 1KARIB0 
SOUTH  CAROLINA  FLORIDA 
216UK7SZ  ASSIGNED  PERSONNEL 
VI  NERO  54066IKARIB0 

KCUBA  ANTILLES  SANTA  DOM I  GO 
1 

FURIOZEGA  400625KARIB0 
CUBA 


r^5  8201  9006222231 

3  ABN  DI  v  KALAFO  9039  16KARIP0 

ONMOHL.TH  G/D  CURA 

690  8376  9266221221 

1C  ARTY  DIV  AKSETO  26629 1KARI BO 

US  MID  ATLANTIC  ST 

485  4192  46771 1 1 1 1213UK65S  ASSIGNED  PERSONNEL 
6  F  SSM  DIV  PARO  373014KARIP0 

US  MID  ATLANTIC  ST 


4  6  5  4067  45521  11001 

6  SAM  PDE  ARGENT 0  713345KARIB0 

US  MID  ATLANTIC  ST 


184  2020  22041 11111 

11  CML  PDE  AKKO  728771KARIB0 

FODOR, V  J  COL  NORTH  CAROLINA 

139  1785  1924111111 

22  ENG  AMPH  REGT  S72163KARIB0 

US  MID  ATLANTIC  ST 

87  650  937000001 

18  SIG  HEOT  ANSIS  614592KARIB0 

US  MID  ATLANTIC  ST 

320  1701  2021000001 

7 s  ENG  AMPH  REGT  1  73745KAHIB0 

US  MID  ATLANTIC  ST 


E-  5 


0 

O’ROURKE, TJ  G/A’S 

# 

O’ROURKE, TJ  G/A’S 

# 

KIYAGISHIMA, TG/A ’S 

0 

MIYAGISHIMA, TG/A  ’S 

# 

MIYAGI SHIMA, TG/A  ’S 


MIYAGISHIMA, TG/A ’S 
US  MID  ATLANTIC  ST 

# 

MIYAGI SHIMA, TG/A ’ S 

0 

MIYAGISHIMA, TG/A  *S 

0 

MIYAGISHIMA,  TG/A ’S 

0 

MIYAGISHIMA, TG/A ’S 

0 

MIYAGISHIMA,  TG/A ’S 

0 

MIYAGISHIMA, TG/A ’S 

# 

MIYAGISHIMA, TG/A  *S 

0 

MIYAGISHIMA,  TG/A ’S 

0 

MIYAGI SHIMA, TG/A ’S 


85  640  925000001 


Ei 


0 

DECLARE  UNAME  STRC 7*25)  * 

DECLARE  CNAME  STRC26*37)  * 

DECLARE  CNO  NUMC 38*43)  * 

DECLARE  PUNA WE  STRC  *44*54)  0 

DECLARE  PUCMDh  STRC 55* 67)  * 
DECLARE  PJCMDRRNK  STRC 68* 72)  0 
DECLARE  NO OFF  NUMC 167* 170)  0 

DECLAnE  UCMDR  STRC87*101)  * 

DECLARE  UCMDRKNK  STRC 102, 106)  0 
DECLARE  ULOCAT  STRC 107* 152)  0 
DECLARE  NO EM  NUMC 171 *175)  • 
DECLARE  NOTL  NUMfl76*180)  » 
DECLARE  MORALE  NUM(181*181>  0 
DECLARE  DISCIPLINE  NUMC 182* 182)  # 
DECLARE  POLITREL  NUMC 183* 183)  0 
DECLARE  EFFIC  NUMC 184* 164)  0 
DECLARE  CPTEFFECT  NUMC 165* 185)  # 
DECLARE  C9TP.ED  NUMC 166, 166)  0 
DECLARE  TIME  i>TRC  1  8  7,  1  90  )  0 
DECLARE  REASON  STRC 19 1*21 5)  # 
DECLARE  TNAME  STRC 7*43)  * 

DECLARE  PERSONNEL  STRC 16  7* 180)  # 
DECLARE  URATINGS  STRC  181*  185)  # 
DECLARE  TCBTHED  STRC 166*21 5)  » 
DEFINE  HNAME=CNAME  * 

DEFINE  P  J  N I T  =  P  UNAK  E  0 
DEFINE  L 0 NAM = ULOCAT  0 
DEFINE  P EK OF* NOO FF  0 
DEFINE  P  ER  EM =  NO EM  0 
DEFINE  PEHTL-NOTL  0 
DEFINE  DEPEN1 =MOKALE  0 
DEFINE  DEPEN2=DI SCIPLI NE  0 
DEFINE  DEPEN3*P0LI TREL  0 
DEFINE  CEPEN4-EFFIC  0 
DEFINE  DEPEN5® CPTEFFECT  0 
DEFINE  CRCAT=CBTRED  0 
DEFINE  CATO  1 =  T I  ME  0 
DEFINE  REAS  1 “REASON  0 

;  s 


